X-Git-Url: http://ftp.carnet.hr/carnet-debian/scm?p=ossec-hids.git;a=blobdiff_plain;f=src%2Fexternal%2Fpcre2-10.32%2Fdoc%2Fpcre2api.3;fp=src%2Fexternal%2Fpcre2-10.32%2Fdoc%2Fpcre2api.3;h=ba90c86d0540a153f6f2df05759f66d7cdaaf181;hp=0000000000000000000000000000000000000000;hb=3f728675941dc69d4e544d3a880a56240a6e394a;hpb=927951d1c1ad45ba9e7325f07d996154a91c911b diff --git a/src/external/pcre2-10.32/doc/pcre2api.3 b/src/external/pcre2-10.32/doc/pcre2api.3 new file mode 100644 index 0000000..ba90c86 --- /dev/null +++ b/src/external/pcre2-10.32/doc/pcre2api.3 @@ -0,0 +1,3675 @@ +.TH PCRE2API 3 "07 September 2018" "PCRE2 10.32" +.SH NAME +PCRE2 - Perl-compatible regular expressions (revised API) +.sp +.B #include +.sp +PCRE2 is a new API for PCRE, starting at release 10.0. This document contains a +description of all its native functions. See the +.\" HREF +\fBpcre2\fP +.\" +document for an overview of all the PCRE2 documentation. +. +. +.SH "PCRE2 NATIVE API BASIC FUNCTIONS" +.rs +.sp +.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);" +.sp +.B void pcre2_code_free(pcre2_code *\fIcode\fP); +.sp +.B pcre2_match_data *pcre2_match_data_create(uint32_t \fIovecsize\fP, +.B " pcre2_general_context *\fIgcontext\fP);" +.sp +.B pcre2_match_data *pcre2_match_data_create_from_pattern( +.B " const pcre2_code *\fIcode\fP, pcre2_general_context *\fIgcontext\fP);" +.sp +.B int pcre2_match(const pcre2_code *\fIcode\fP, PCRE2_SPTR \fIsubject\fP, +.B " PCRE2_SIZE \fIlength\fP, PCRE2_SIZE \fIstartoffset\fP," +.B " uint32_t \fIoptions\fP, pcre2_match_data *\fImatch_data\fP," +.B " pcre2_match_context *\fImcontext\fP);" +.sp +.B int pcre2_dfa_match(const pcre2_code *\fIcode\fP, PCRE2_SPTR \fIsubject\fP, +.B " PCRE2_SIZE \fIlength\fP, PCRE2_SIZE \fIstartoffset\fP," +.B " uint32_t \fIoptions\fP, pcre2_match_data *\fImatch_data\fP," +.B " pcre2_match_context *\fImcontext\fP," +.B " int *\fIworkspace\fP, PCRE2_SIZE \fIwscount\fP);" +.sp +.B void pcre2_match_data_free(pcre2_match_data *\fImatch_data\fP); +.fi +. +. +.SH "PCRE2 NATIVE API AUXILIARY MATCH FUNCTIONS" +.rs +.sp +.nf +.B PCRE2_SPTR pcre2_get_mark(pcre2_match_data *\fImatch_data\fP); +.sp +.B uint32_t pcre2_get_ovector_count(pcre2_match_data *\fImatch_data\fP); +.sp +.B PCRE2_SIZE *pcre2_get_ovector_pointer(pcre2_match_data *\fImatch_data\fP); +.sp +.B PCRE2_SIZE pcre2_get_startchar(pcre2_match_data *\fImatch_data\fP); +.fi +. +. +.SH "PCRE2 NATIVE API GENERAL CONTEXT FUNCTIONS" +.rs +.sp +.nf +.B pcre2_general_context *pcre2_general_context_create( +.B " void *(*\fIprivate_malloc\fP)(PCRE2_SIZE, void *)," +.B " void (*\fIprivate_free\fP)(void *, void *), void *\fImemory_data\fP);" +.sp +.B pcre2_general_context *pcre2_general_context_copy( +.B " pcre2_general_context *\fIgcontext\fP);" +.sp +.B void pcre2_general_context_free(pcre2_general_context *\fIgcontext\fP); +.fi +. +. +.SH "PCRE2 NATIVE API COMPILE CONTEXT FUNCTIONS" +.rs +.sp +.nf +.B pcre2_compile_context *pcre2_compile_context_create( +.B " pcre2_general_context *\fIgcontext\fP);" +.sp +.B pcre2_compile_context *pcre2_compile_context_copy( +.B " pcre2_compile_context *\fIccontext\fP);" +.sp +.B void pcre2_compile_context_free(pcre2_compile_context *\fIccontext\fP); +.sp +.B int pcre2_set_bsr(pcre2_compile_context *\fIccontext\fP, +.B " uint32_t \fIvalue\fP);" +.sp +.B int pcre2_set_character_tables(pcre2_compile_context *\fIccontext\fP, +.B " const unsigned char *\fItables\fP);" +.sp +.B int pcre2_set_compile_extra_options(pcre2_compile_context *\fIccontext\fP, +.B " uint32_t \fIextra_options\fP);" +.sp +.B int pcre2_set_max_pattern_length(pcre2_compile_context *\fIccontext\fP, +.B " PCRE2_SIZE \fIvalue\fP);" +.sp +.B int pcre2_set_newline(pcre2_compile_context *\fIccontext\fP, +.B " uint32_t \fIvalue\fP);" +.sp +.B int pcre2_set_parens_nest_limit(pcre2_compile_context *\fIccontext\fP, +.B " uint32_t \fIvalue\fP);" +.sp +.B int pcre2_set_compile_recursion_guard(pcre2_compile_context *\fIccontext\fP, +.B " int (*\fIguard_function\fP)(uint32_t, void *), void *\fIuser_data\fP);" +.fi +. +. +.SH "PCRE2 NATIVE API MATCH CONTEXT FUNCTIONS" +.rs +.sp +.nf +.B pcre2_match_context *pcre2_match_context_create( +.B " pcre2_general_context *\fIgcontext\fP);" +.sp +.B pcre2_match_context *pcre2_match_context_copy( +.B " pcre2_match_context *\fImcontext\fP);" +.sp +.B void pcre2_match_context_free(pcre2_match_context *\fImcontext\fP); +.sp +.B int pcre2_set_callout(pcre2_match_context *\fImcontext\fP, +.B " int (*\fIcallout_function\fP)(pcre2_callout_block *, void *)," +.B " void *\fIcallout_data\fP);" +.sp +.B int pcre2_set_offset_limit(pcre2_match_context *\fImcontext\fP, +.B " PCRE2_SIZE \fIvalue\fP);" +.sp +.B int pcre2_set_heap_limit(pcre2_match_context *\fImcontext\fP, +.B " uint32_t \fIvalue\fP);" +.sp +.B int pcre2_set_match_limit(pcre2_match_context *\fImcontext\fP, +.B " uint32_t \fIvalue\fP);" +.sp +.B int pcre2_set_depth_limit(pcre2_match_context *\fImcontext\fP, +.B " uint32_t \fIvalue\fP);" +.fi +. +. +.SH "PCRE2 NATIVE API STRING EXTRACTION FUNCTIONS" +.rs +.sp +.nf +.B int pcre2_substring_copy_byname(pcre2_match_data *\fImatch_data\fP, +.B " PCRE2_SPTR \fIname\fP, PCRE2_UCHAR *\fIbuffer\fP, PCRE2_SIZE *\fIbufflen\fP);" +.sp +.B int pcre2_substring_copy_bynumber(pcre2_match_data *\fImatch_data\fP, +.B " uint32_t \fInumber\fP, PCRE2_UCHAR *\fIbuffer\fP," +.B " PCRE2_SIZE *\fIbufflen\fP);" +.sp +.B void pcre2_substring_free(PCRE2_UCHAR *\fIbuffer\fP); +.sp +.B int pcre2_substring_get_byname(pcre2_match_data *\fImatch_data\fP, +.B " PCRE2_SPTR \fIname\fP, PCRE2_UCHAR **\fIbufferptr\fP, PCRE2_SIZE *\fIbufflen\fP);" +.sp +.B int pcre2_substring_get_bynumber(pcre2_match_data *\fImatch_data\fP, +.B " uint32_t \fInumber\fP, PCRE2_UCHAR **\fIbufferptr\fP," +.B " PCRE2_SIZE *\fIbufflen\fP);" +.sp +.B int pcre2_substring_length_byname(pcre2_match_data *\fImatch_data\fP, +.B " PCRE2_SPTR \fIname\fP, PCRE2_SIZE *\fIlength\fP);" +.sp +.B int pcre2_substring_length_bynumber(pcre2_match_data *\fImatch_data\fP, +.B " uint32_t \fInumber\fP, PCRE2_SIZE *\fIlength\fP);" +.sp +.B int pcre2_substring_nametable_scan(const pcre2_code *\fIcode\fP, +.B " PCRE2_SPTR \fIname\fP, PCRE2_SPTR *\fIfirst\fP, PCRE2_SPTR *\fIlast\fP);" +.sp +.B int pcre2_substring_number_from_name(const pcre2_code *\fIcode\fP, +.B " PCRE2_SPTR \fIname\fP);" +.sp +.B void pcre2_substring_list_free(PCRE2_SPTR *\fIlist\fP); +.sp +.B int pcre2_substring_list_get(pcre2_match_data *\fImatch_data\fP, +.B " PCRE2_UCHAR ***\fIlistptr\fP, PCRE2_SIZE **\fIlengthsptr\fP); +.fi +. +. +.SH "PCRE2 NATIVE API STRING SUBSTITUTION FUNCTION" +.rs +.sp +.nf +.B int pcre2_substitute(const pcre2_code *\fIcode\fP, PCRE2_SPTR \fIsubject\fP, +.B " PCRE2_SIZE \fIlength\fP, PCRE2_SIZE \fIstartoffset\fP," +.B " uint32_t \fIoptions\fP, pcre2_match_data *\fImatch_data\fP," +.B " pcre2_match_context *\fImcontext\fP, PCRE2_SPTR \fIreplacementzfP," +.B " PCRE2_SIZE \fIrlength\fP, PCRE2_UCHAR *\fIoutputbuffer\fP," +.B " PCRE2_SIZE *\fIoutlengthptr\fP);" +.fi +. +. +.SH "PCRE2 NATIVE API JIT FUNCTIONS" +.rs +.sp +.nf +.B int pcre2_jit_compile(pcre2_code *\fIcode\fP, uint32_t \fIoptions\fP); +.sp +.B int pcre2_jit_match(const pcre2_code *\fIcode\fP, PCRE2_SPTR \fIsubject\fP, +.B " PCRE2_SIZE \fIlength\fP, PCRE2_SIZE \fIstartoffset\fP," +.B " uint32_t \fIoptions\fP, pcre2_match_data *\fImatch_data\fP," +.B " pcre2_match_context *\fImcontext\fP);" +.sp +.B void pcre2_jit_free_unused_memory(pcre2_general_context *\fIgcontext\fP); +.sp +.B pcre2_jit_stack *pcre2_jit_stack_create(PCRE2_SIZE \fIstartsize\fP, +.B " PCRE2_SIZE \fImaxsize\fP, pcre2_general_context *\fIgcontext\fP);" +.sp +.B void pcre2_jit_stack_assign(pcre2_match_context *\fImcontext\fP, +.B " pcre2_jit_callback \fIcallback_function\fP, void *\fIcallback_data\fP);" +.sp +.B void pcre2_jit_stack_free(pcre2_jit_stack *\fIjit_stack\fP); +.fi +. +. +.SH "PCRE2 NATIVE API SERIALIZATION FUNCTIONS" +.rs +.sp +.nf +.B int32_t pcre2_serialize_decode(pcre2_code **\fIcodes\fP, +.B " int32_t \fInumber_of_codes\fP, const uint8_t *\fIbytes\fP," +.B " pcre2_general_context *\fIgcontext\fP);" +.sp +.B int32_t pcre2_serialize_encode(const pcre2_code **\fIcodes\fP, +.B " int32_t \fInumber_of_codes\fP, uint8_t **\fIserialized_bytes\fP," +.B " PCRE2_SIZE *\fIserialized_size\fP, pcre2_general_context *\fIgcontext\fP);" +.sp +.B void pcre2_serialize_free(uint8_t *\fIbytes\fP); +.sp +.B int32_t pcre2_serialize_get_number_of_codes(const uint8_t *\fIbytes\fP); +.fi +. +. +.SH "PCRE2 NATIVE API AUXILIARY FUNCTIONS" +.rs +.sp +.nf +.B pcre2_code *pcre2_code_copy(const pcre2_code *\fIcode\fP); +.sp +.B pcre2_code *pcre2_code_copy_with_tables(const pcre2_code *\fIcode\fP); +.sp +.B int pcre2_get_error_message(int \fIerrorcode\fP, PCRE2_UCHAR *\fIbuffer\fP, +.B " PCRE2_SIZE \fIbufflen\fP);" +.sp +.B const unsigned char *pcre2_maketables(pcre2_general_context *\fIgcontext\fP); +.sp +.B int pcre2_pattern_info(const pcre2 *\fIcode\fP, uint32_t \fIwhat\fP, void *\fIwhere\fP); +.sp +.B int pcre2_callout_enumerate(const pcre2_code *\fIcode\fP, +.B " int (*\fIcallback\fP)(pcre2_callout_enumerate_block *, void *)," +.B " void *\fIuser_data\fP);" +.sp +.B int pcre2_config(uint32_t \fIwhat\fP, void *\fIwhere\fP); +.fi +. +. +.SH "PCRE2 NATIVE API OBSOLETE FUNCTIONS" +.rs +.sp +.nf +.B int pcre2_set_recursion_limit(pcre2_match_context *\fImcontext\fP, +.B " uint32_t \fIvalue\fP);" +.sp +.B int pcre2_set_recursion_memory_management( +.B " pcre2_match_context *\fImcontext\fP," +.B " void *(*\fIprivate_malloc\fP)(PCRE2_SIZE, void *)," +.B " void (*\fIprivate_free\fP)(void *, void *), void *\fImemory_data\fP);" +.fi +.sp +These functions became obsolete at release 10.30 and are retained only for +backward compatibility. They should not be used in new code. The first is +replaced by \fBpcre2_set_depth_limit()\fP; the second is no longer needed and +has no effect (it always returns zero). +. +. +.SH "PCRE2 EXPERIMENTAL PATTERN CONVERSION FUNCTIONS" +.rs +.sp +.nf +.B pcre2_convert_context *pcre2_convert_context_create( +.B " pcre2_general_context *\fIgcontext\fP);" +.sp +.B pcre2_convert_context *pcre2_convert_context_copy( +.B " pcre2_convert_context *\fIcvcontext\fP);" +.sp +.B void pcre2_convert_context_free(pcre2_convert_context *\fIcvcontext\fP); +.sp +.B int pcre2_set_glob_escape(pcre2_convert_context *\fIcvcontext\fP, +.B " uint32_t \fIescape_char\fP);" +.sp +.B int pcre2_set_glob_separator(pcre2_convert_context *\fIcvcontext\fP, +.B " uint32_t \fIseparator_char\fP);" +.sp +.B int pcre2_pattern_convert(PCRE2_SPTR \fIpattern\fP, PCRE2_SIZE \fIlength\fP, +.B " uint32_t \fIoptions\fP, PCRE2_UCHAR **\fIbuffer\fP," +.B " PCRE2_SIZE *\fIblength\fP, pcre2_convert_context *\fIcvcontext\fP);" +.sp +.B void pcre2_converted_pattern_free(PCRE2_UCHAR *\fIconverted_pattern\fP); +.fi +.sp +These functions provide a way of converting non-PCRE2 patterns into +patterns that can be processed by \fBpcre2_compile()\fP. This facility is +experimental and may be changed in future releases. At present, "globs" and +POSIX basic and extended patterns can be converted. Details are given in the +.\" HREF +\fBpcre2convert\fP +.\" +documentation. +. +. +.SH "PCRE2 8-BIT, 16-BIT, AND 32-BIT LIBRARIES" +.rs +.sp +There are three PCRE2 libraries, supporting 8-bit, 16-bit, and 32-bit code +units, respectively. However, there is just one header file, \fBpcre2.h\fP. +This contains the function prototypes and other definitions for all three +libraries. One, two, or all three can be installed simultaneously. On Unix-like +systems the libraries are called \fBlibpcre2-8\fP, \fBlibpcre2-16\fP, and +\fBlibpcre2-32\fP, and they can also co-exist with the original PCRE libraries. +.P +Character strings are passed to and from a PCRE2 library as a sequence of +unsigned integers in code units of the appropriate width. Every PCRE2 function +comes in three different forms, one for each library, for example: +.sp + \fBpcre2_compile_8()\fP + \fBpcre2_compile_16()\fP + \fBpcre2_compile_32()\fP +.sp +There are also three different sets of data types: +.sp + \fBPCRE2_UCHAR8, PCRE2_UCHAR16, PCRE2_UCHAR32\fP + \fBPCRE2_SPTR8, PCRE2_SPTR16, PCRE2_SPTR32\fP +.sp +The UCHAR types define unsigned code units of the appropriate widths. For +example, PCRE2_UCHAR16 is usually defined as `uint16_t'. The SPTR types are +constant pointers to the equivalent UCHAR types, that is, they are pointers to +vectors of unsigned code units. +.P +Many applications use only one code unit width. For their convenience, macros +are defined whose names are the generic forms such as \fBpcre2_compile()\fP and +PCRE2_SPTR. These macros use the value of the macro PCRE2_CODE_UNIT_WIDTH to +generate the appropriate width-specific function and macro names. +PCRE2_CODE_UNIT_WIDTH is not defined by default. An application must define it +to be 8, 16, or 32 before including \fBpcre2.h\fP in order to make use of the +generic names. +.P +Applications that use more than one code unit width can be linked with more +than one PCRE2 library, but must define PCRE2_CODE_UNIT_WIDTH to be 0 before +including \fBpcre2.h\fP, and then use the real function names. Any code that is +to be included in an environment where the value of PCRE2_CODE_UNIT_WIDTH is +unknown should also use the real function names. (Unfortunately, it is not +possible in C code to save and restore the value of a macro.) +.P +If PCRE2_CODE_UNIT_WIDTH is not defined before including \fBpcre2.h\fP, a +compiler error occurs. +.P +When using multiple libraries in an application, you must take care when +processing any particular pattern to use only functions from a single library. +For example, if you want to run a match using a pattern that was compiled with +\fBpcre2_compile_16()\fP, you must do so with \fBpcre2_match_16()\fP, not +\fBpcre2_match_8()\fP or \fBpcre2_match_32()\fP. +.P +In the function summaries above, and in the rest of this document and other +PCRE2 documents, functions and data types are described using their generic +names, without the _8, _16, or _32 suffix. +. +. +.SH "PCRE2 API OVERVIEW" +.rs +.sp +PCRE2 has its own native API, which is described in this document. There are +also some wrapper functions for the 8-bit library that correspond to the +POSIX regular expression API, but they do not give access to all the +functionality of PCRE2. They are described in the +.\" HREF +\fBpcre2posix\fP +.\" +documentation. Both these APIs define a set of C function calls. +.P +The native API C data types, function prototypes, option values, and error +codes are defined in the header file \fBpcre2.h\fP, which also contains +definitions of PCRE2_MAJOR and PCRE2_MINOR, the major and minor release numbers +for the library. Applications can use these to include support for different +releases of PCRE2. +.P +In a Windows environment, if you want to statically link an application program +against a non-dll PCRE2 library, you must define PCRE2_STATIC before including +\fBpcre2.h\fP. +.P +The functions \fBpcre2_compile()\fP and \fBpcre2_match()\fP are used for +compiling and matching regular expressions in a Perl-compatible manner. A +sample program that demonstrates the simplest way of using them is provided in +the file called \fIpcre2demo.c\fP in the PCRE2 source distribution. A listing +of this program is given in the +.\" HREF +\fBpcre2demo\fP +.\" +documentation, and the +.\" HREF +\fBpcre2sample\fP +.\" +documentation describes how to compile and run it. +.P +The compiling and matching functions recognize various options that are passed +as bits in an options argument. There are also some more complicated parameters +such as custom memory management functions and resource limits that are passed +in "contexts" (which are just memory blocks, described below). Simple +applications do not need to make use of contexts. +.P +Just-in-time (JIT) compiler support is an optional feature of PCRE2 that can be +built in appropriate hardware environments. It greatly speeds up the matching +performance of many patterns. Programs can request that it be used if +available by calling \fBpcre2_jit_compile()\fP after a pattern has been +successfully compiled by \fBpcre2_compile()\fP. This does nothing if JIT +support is not available. +.P +More complicated programs might need to make use of the specialist functions +\fBpcre2_jit_stack_create()\fP, \fBpcre2_jit_stack_free()\fP, and +\fBpcre2_jit_stack_assign()\fP in order to control the JIT code's memory usage. +.P +JIT matching is automatically used by \fBpcre2_match()\fP if it is available, +unless the PCRE2_NO_JIT option is set. There is also a direct interface for JIT +matching, which gives improved performance at the expense of less sanity +checking. The JIT-specific functions are discussed in the +.\" HREF +\fBpcre2jit\fP +.\" +documentation. +.P +A second matching function, \fBpcre2_dfa_match()\fP, which is not +Perl-compatible, is also provided. This uses a different algorithm for the +matching. The alternative algorithm finds all possible matches (at a given +point in the subject), and scans the subject just once (unless there are +lookaround assertions). However, this algorithm does not return captured +substrings. A description of the two matching algorithms and their advantages +and disadvantages is given in the +.\" HREF +\fBpcre2matching\fP +.\" +documentation. There is no JIT support for \fBpcre2_dfa_match()\fP. +.P +In addition to the main compiling and matching functions, there are convenience +functions for extracting captured substrings from a subject string that has +been matched by \fBpcre2_match()\fP. They are: +.sp + \fBpcre2_substring_copy_byname()\fP + \fBpcre2_substring_copy_bynumber()\fP + \fBpcre2_substring_get_byname()\fP + \fBpcre2_substring_get_bynumber()\fP + \fBpcre2_substring_list_get()\fP + \fBpcre2_substring_length_byname()\fP + \fBpcre2_substring_length_bynumber()\fP + \fBpcre2_substring_nametable_scan()\fP + \fBpcre2_substring_number_from_name()\fP +.sp +\fBpcre2_substring_free()\fP and \fBpcre2_substring_list_free()\fP are also +provided, to free memory used for extracted strings. If either of these +functions is called with a NULL argument, the function returns immediately +without doing anything. +.P +The function \fBpcre2_substitute()\fP can be called to match a pattern and +return a copy of the subject string with substitutions for parts that were +matched. +.P +Functions whose names begin with \fBpcre2_serialize_\fP are used for saving +compiled patterns on disc or elsewhere, and reloading them later. +.P +Finally, there are functions for finding out information about a compiled +pattern (\fBpcre2_pattern_info()\fP) and about the configuration with which +PCRE2 was built (\fBpcre2_config()\fP). +.P +Functions with names ending with \fB_free()\fP are used for freeing memory +blocks of various sorts. In all cases, if one of these functions is called with +a NULL argument, it does nothing. +. +. +.SH "STRING LENGTHS AND OFFSETS" +.rs +.sp +The PCRE2 API uses string lengths and offsets into strings of code units in +several places. These values are always of type PCRE2_SIZE, which is an +unsigned integer type, currently always defined as \fIsize_t\fP. The largest +value that can be stored in such a type (that is ~(PCRE2_SIZE)0) is reserved +as a special indicator for zero-terminated strings and unset offsets. +Therefore, the longest string that can be handled is one less than this +maximum. +. +. +.\" HTML +.SH NEWLINES +.rs +.sp +PCRE2 supports five different conventions for indicating line breaks in +strings: a single CR (carriage return) character, a single LF (linefeed) +character, the two-character sequence CRLF, any of the three preceding, or any +Unicode newline sequence. The Unicode newline sequences are the three just +mentioned, plus the single characters VT (vertical tab, U+000B), FF (form feed, +U+000C), NEL (next line, U+0085), LS (line separator, U+2028), and PS +(paragraph separator, U+2029). +.P +Each of the first three conventions is used by at least one operating system as +its standard newline sequence. When PCRE2 is built, a default can be specified. +If it is not, the default is set to LF, which is the Unix standard. However, +the newline convention can be changed by an application when calling +\fBpcre2_compile()\fP, or it can be specified by special text at the start of +the pattern itself; this overrides any other settings. See the +.\" HREF +\fBpcre2pattern\fP +.\" +page for details of the special character sequences. +.P +In the PCRE2 documentation the word "newline" is used to mean "the character or +pair of characters that indicate a line break". The choice of newline +convention affects the handling of the dot, circumflex, and dollar +metacharacters, the handling of #-comments in /x mode, and, when CRLF is a +recognized line ending sequence, the match position advancement for a +non-anchored pattern. There is more detail about this in the +.\" HTML +.\" +section on \fBpcre2_match()\fP options +.\" +below. +.P +The choice of newline convention does not affect the interpretation of +the \en or \er escape sequences, nor does it affect what \eR matches; this has +its own separate convention. +. +. +.SH MULTITHREADING +.rs +.sp +In a multithreaded application it is important to keep thread-specific data +separate from data that can be shared between threads. The PCRE2 library code +itself is thread-safe: it contains no static or global variables. The API is +designed to be fairly simple for non-threaded applications while at the same +time ensuring that multithreaded applications can use it. +.P +There are several different blocks of data that are used to pass information +between the application and the PCRE2 libraries. +. +. +.SS "The compiled pattern" +.rs +.sp +A pointer to the compiled form of a pattern is returned to the user when +\fBpcre2_compile()\fP is successful. The data in the compiled pattern is fixed, +and does not change when the pattern is matched. Therefore, it is thread-safe, +that is, the same compiled pattern can be used by more than one thread +simultaneously. For example, an application can compile all its patterns at the +start, before forking off multiple threads that use them. However, if the +just-in-time (JIT) optimization feature is being used, it needs separate memory +stack areas for each thread. See the +.\" HREF +\fBpcre2jit\fP +.\" +documentation for more details. +.P +In a more complicated situation, where patterns are compiled only when they are +first needed, but are still shared between threads, pointers to compiled +patterns must be protected from simultaneous writing by multiple threads, at +least until a pattern has been compiled. The logic can be something like this: +.sp + Get a read-only (shared) lock (mutex) for pointer + if (pointer == NULL) + { + Get a write (unique) lock for pointer + pointer = pcre2_compile(... + } + Release the lock + Use pointer in pcre2_match() +.sp +Of course, testing for compilation errors should also be included in the code. +.P +If JIT is being used, but the JIT compilation is not being done immediately, +(perhaps waiting to see if the pattern is used often enough) similar logic is +required. JIT compilation updates a pointer within the compiled code block, so +a thread must gain unique write access to the pointer before calling +\fBpcre2_jit_compile()\fP. Alternatively, \fBpcre2_code_copy()\fP or +\fBpcre2_code_copy_with_tables()\fP can be used to obtain a private copy of the +compiled code before calling the JIT compiler. +. +. +.SS "Context blocks" +.rs +.sp +The next main section below introduces the idea of "contexts" in which PCRE2 +functions are called. A context is nothing more than a collection of parameters +that control the way PCRE2 operates. Grouping a number of parameters together +in a context is a convenient way of passing them to a PCRE2 function without +using lots of arguments. The parameters that are stored in contexts are in some +sense "advanced features" of the API. Many straightforward applications will +not need to use contexts. +.P +In a multithreaded application, if the parameters in a context are values that +are never changed, the same context can be used by all the threads. However, if +any thread needs to change any value in a context, it must make its own +thread-specific copy. +. +. +.SS "Match blocks" +.rs +.sp +The matching functions need a block of memory for storing the results of a +match. This includes details of what was matched, as well as additional +information such as the name of a (*MARK) setting. Each thread must provide its +own copy of this memory. +. +. +.SH "PCRE2 CONTEXTS" +.rs +.sp +Some PCRE2 functions have a lot of parameters, many of which are used only by +specialist applications, for example, those that use custom memory management +or non-standard character tables. To keep function argument lists at a +reasonable size, and at the same time to keep the API extensible, "uncommon" +parameters are passed to certain functions in a \fBcontext\fP instead of +directly. A context is just a block of memory that holds the parameter values. +Applications that do not need to adjust any of the context parameters can pass +NULL when a context pointer is required. +.P +There are three different types of context: a general context that is relevant +for several PCRE2 operations, a compile-time context, and a match-time context. +. +. +.SS "The general context" +.rs +.sp +At present, this context just contains pointers to (and data for) external +memory management functions that are called from several places in the PCRE2 +library. The context is named `general' rather than specifically `memory' +because in future other fields may be added. If you do not want to supply your +own custom memory management functions, you do not need to bother with a +general context. A general context is created by: +.sp +.nf +.B pcre2_general_context *pcre2_general_context_create( +.B " void *(*\fIprivate_malloc\fP)(PCRE2_SIZE, void *)," +.B " void (*\fIprivate_free\fP)(void *, void *), void *\fImemory_data\fP);" +.fi +.sp +The two function pointers specify custom memory management functions, whose +prototypes are: +.sp + \fBvoid *private_malloc(PCRE2_SIZE, void *);\fP + \fBvoid private_free(void *, void *);\fP +.sp +Whenever code in PCRE2 calls these functions, the final argument is the value +of \fImemory_data\fP. Either of the first two arguments of the creation +function may be NULL, in which case the system memory management functions +\fImalloc()\fP and \fIfree()\fP are used. (This is not currently useful, as +there are no other fields in a general context, but in future there might be.) +The \fIprivate_malloc()\fP function is used (if supplied) to obtain memory for +storing the context, and all three values are saved as part of the context. +.P +Whenever PCRE2 creates a data block of any kind, the block contains a pointer +to the \fIfree()\fP function that matches the \fImalloc()\fP function that was +used. When the time comes to free the block, this function is called. +.P +A general context can be copied by calling: +.sp +.nf +.B pcre2_general_context *pcre2_general_context_copy( +.B " pcre2_general_context *\fIgcontext\fP);" +.fi +.sp +The memory used for a general context should be freed by calling: +.sp +.nf +.B void pcre2_general_context_free(pcre2_general_context *\fIgcontext\fP); +.fi +.sp +If this function is passed a NULL argument, it returns immediately without +doing anything. +. +. +.\" HTML +.SS "The compile context" +.rs +.sp +A compile context is required if you want to provide an external function for +stack checking during compilation or to change the default values of any of the +following compile-time 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 length of the pattern string + The extra options bits (none set by default) +.sp +A compile context is also required if you are using custom memory management. +If none of these apply, just pass NULL as the context argument of +\fIpcre2_compile()\fP. +.P +A compile context is created, copied, and freed by the following functions: +.sp +.nf +.B pcre2_compile_context *pcre2_compile_context_create( +.B " pcre2_general_context *\fIgcontext\fP);" +.sp +.B pcre2_compile_context *pcre2_compile_context_copy( +.B " pcre2_compile_context *\fIccontext\fP);" +.sp +.B void pcre2_compile_context_free(pcre2_compile_context *\fIccontext\fP); +.fi +.sp +A compile context is created with default values for its parameters. These can +be changed by calling the following functions, which return 0 on success, or +PCRE2_ERROR_BADDATA if invalid data is detected. +.sp +.nf +.B int pcre2_set_bsr(pcre2_compile_context *\fIccontext\fP, +.B " uint32_t \fIvalue\fP);" +.fi +.sp +The value must be PCRE2_BSR_ANYCRLF, to specify that \eR matches only CR, LF, +or CRLF, or PCRE2_BSR_UNICODE, to specify that \eR matches any Unicode line +ending sequence. The value is used by the JIT compiler and by the two +interpreted matching functions, \fIpcre2_match()\fP and +\fIpcre2_dfa_match()\fP. +.sp +.nf +.B int pcre2_set_character_tables(pcre2_compile_context *\fIccontext\fP, +.B " const unsigned char *\fItables\fP);" +.fi +.sp +The value must be the result of a call to \fIpcre2_maketables()\fP, whose only +argument is a general context. This function builds a set of character tables +in the current locale. +.sp +.nf +.B int pcre2_set_compile_extra_options(pcre2_compile_context *\fIccontext\fP, +.B " uint32_t \fIextra_options\fP);" +.fi +.sp +As PCRE2 has developed, almost all the 32 option bits that are available in +the \fIoptions\fP argument of \fBpcre2_compile()\fP have been used up. To avoid +running out, the compile context contains a set of extra option bits which are +used for some newer, assumed rarer, options. This function sets those bits. It +always sets all the bits (either on or off). It does not modify any existing +setting. The available options are defined in the section entitled "Extra +compile options" +.\" HTML +.\" +below. +.\" +.sp +.nf +.B int pcre2_set_max_pattern_length(pcre2_compile_context *\fIccontext\fP, +.B " PCRE2_SIZE \fIvalue\fP);" +.fi +.sp +This sets a maximum length, in code units, for any pattern string that is +compiled with this context. If the pattern is longer, an error is generated. +This facility is provided so that applications that accept patterns from +external sources can limit their size. The default is the largest number that a +PCRE2_SIZE variable can hold, which is effectively unlimited. +.sp +.nf +.B int pcre2_set_newline(pcre2_compile_context *\fIccontext\fP, +.B " uint32_t \fIvalue\fP);" +.fi +.sp +This specifies which characters or character sequences are to be recognized as +newlines. The value must be one of PCRE2_NEWLINE_CR (carriage return only), +PCRE2_NEWLINE_LF (linefeed only), PCRE2_NEWLINE_CRLF (the two-character +sequence CR followed by LF), PCRE2_NEWLINE_ANYCRLF (any of the above), +PCRE2_NEWLINE_ANY (any Unicode newline sequence), or PCRE2_NEWLINE_NUL (the +NUL character, that is a binary zero). +.P +A pattern can override the value set in the compile context by starting with a +sequence such as (*CRLF). See the +.\" HREF +\fBpcre2pattern\fP +.\" +page for details. +.P +When a pattern is compiled with the PCRE2_EXTENDED or PCRE2_EXTENDED_MORE +option, the newline convention affects the recognition of the end of internal +comments starting with #. The value is saved with the compiled pattern for +subsequent use by the JIT compiler and by the two interpreted matching +functions, \fIpcre2_match()\fP and \fIpcre2_dfa_match()\fP. +.sp +.nf +.B int pcre2_set_parens_nest_limit(pcre2_compile_context *\fIccontext\fP, +.B " uint32_t \fIvalue\fP);" +.fi +.sp +This parameter ajusts the limit, set when PCRE2 is built (default 250), on the +depth of parenthesis nesting in a pattern. This limit stops rogue patterns +using up too much system stack when being compiled. The limit applies to +parentheses of all kinds, not just capturing parentheses. +.sp +.nf +.B int pcre2_set_compile_recursion_guard(pcre2_compile_context *\fIccontext\fP, +.B " int (*\fIguard_function\fP)(uint32_t, void *), void *\fIuser_data\fP);" +.fi +.sp +There is at least one application that runs PCRE2 in threads with very limited +system stack, where running out of stack is to be avoided at all costs. The +parenthesis limit above cannot take account of how much stack is actually +available during compilation. For a finer control, you can supply a function +that is called whenever \fBpcre2_compile()\fP starts to compile a parenthesized +part of a pattern. This function can check the actual stack size (or anything +else that it wants to, of course). +.P +The first argument to the callout function gives the current depth of +nesting, and the second is user data that is set up by the last argument of +\fBpcre2_set_compile_recursion_guard()\fP. The callout function should return +zero if all is well, or non-zero to force an error. +. +. +.\" HTML +.SS "The match context" +.rs +.sp +A match context is required if you want to: +.sp + Set up a callout function + Set an offset limit for matching an unanchored pattern + Change the limit on the amount of heap used when matching + Change the backtracking match limit + Change the backtracking depth limit + Set custom memory management specifically for the match +.sp +If none of these apply, just pass NULL as the context argument of +\fBpcre2_match()\fP, \fBpcre2_dfa_match()\fP, or \fBpcre2_jit_match()\fP. +.P +A match context is created, copied, and freed by the following functions: +.sp +.nf +.B pcre2_match_context *pcre2_match_context_create( +.B " pcre2_general_context *\fIgcontext\fP);" +.sp +.B pcre2_match_context *pcre2_match_context_copy( +.B " pcre2_match_context *\fImcontext\fP);" +.sp +.B void pcre2_match_context_free(pcre2_match_context *\fImcontext\fP); +.fi +.sp +A match context is created with default values for its parameters. These can +be changed by calling the following functions, which return 0 on success, or +PCRE2_ERROR_BADDATA if invalid data is detected. +.sp +.nf +.B int pcre2_set_callout(pcre2_match_context *\fImcontext\fP, +.B " int (*\fIcallout_function\fP)(pcre2_callout_block *, void *)," +.B " void *\fIcallout_data\fP);" +.fi +.sp +This sets up a "callout" function for PCRE2 to call at specified points +during a matching operation. Details are given in the +.\" HREF +\fBpcre2callout\fP +.\" +documentation. +.sp +.nf +.B int pcre2_set_offset_limit(pcre2_match_context *\fImcontext\fP, +.B " PCRE2_SIZE \fIvalue\fP);" +.fi +.sp +The \fIoffset_limit\fP parameter limits how far an unanchored search can +advance in the subject string. The default value is PCRE2_UNSET. The +\fBpcre2_match()\fP and \fBpcre2_dfa_match()\fP functions return +PCRE2_ERROR_NOMATCH if a match with a starting point before or at the given +offset is not found. The \fBpcre2_substitute()\fP function makes no more +substitutions. +.P +For example, if the pattern /abc/ is matched against "123abc" with an offset +limit less than 3, the result is PCRE2_ERROR_NO_MATCH. A match can never be +found if the \fIstartoffset\fP argument of \fBpcre2_match()\fP, +\fBpcre2_dfa_match()\fP, or \fBpcre2_substitute()\fP is greater than the offset +limit set in the match context. +.P +When using this facility, you must set the PCRE2_USE_OFFSET_LIMIT option when +calling \fBpcre2_compile()\fP so that when JIT is in use, different code can be +compiled. If a match is started with a non-default match limit when +PCRE2_USE_OFFSET_LIMIT is not set, an error is generated. +.P +The offset limit facility can be used to track progress when searching large +subject strings or to limit the extent of global substitutions. See also the +PCRE2_FIRSTLINE option, which requires a match to start before or at the first +newline that follows the start of matching in the subject. If this is set with +an offset limit, a match must occur in the first line and also within the +offset limit. In other words, whichever limit comes first is used. +.sp +.nf +.B int pcre2_set_heap_limit(pcre2_match_context *\fImcontext\fP, +.B " uint32_t \fIvalue\fP);" +.fi +.sp +The \fIheap_limit\fP parameter specifies, in units of kibibytes (1024 bytes), +the maximum amount of heap memory that \fBpcre2_match()\fP may use to hold +backtracking information when running an interpretive match. This limit also +applies to \fBpcre2_dfa_match()\fP, which may use the heap when processing +patterns with a lot of nested pattern recursion or lookarounds or atomic +groups. This limit does not apply to matching with the JIT optimization, which +has its own memory control arrangements (see the +.\" HREF +\fBpcre2jit\fP +.\" +documentation for more details). If the limit is reached, the negative error +code PCRE2_ERROR_HEAPLIMIT is returned. The default limit can be set when PCRE2 +is built; if it is not, the default is set very large and is essentially +"unlimited". +.P +A value for the heap limit may also be supplied by an item at the start of a +pattern of the form +.sp + (*LIMIT_HEAP=ddd) +.sp +where ddd is a decimal number. However, such a setting is ignored unless ddd is +less than the limit set by the caller of \fBpcre2_match()\fP or, if no such +limit is set, less than the default. +.P +The \fBpcre2_match()\fP function starts out using a 20KiB vector on the system +stack for recording backtracking points. The more nested backtracking points +there are (that is, the deeper the search tree), the more memory is needed. +Heap memory is used only if the initial vector is too small. If the heap limit +is set to a value less than 21 (in particular, zero) no heap memory will be +used. In this case, only patterns that do not have a lot of nested backtracking +can be successfully processed. +.P +Similarly, for \fBpcre2_dfa_match()\fP, a vector on the system stack is used +when processing pattern recursions, lookarounds, or atomic groups, and only if +this is not big enough is heap memory used. In this case, too, setting a value +of zero disables the use of the heap. +.sp +.nf +.B int pcre2_set_match_limit(pcre2_match_context *\fImcontext\fP, +.B " uint32_t \fIvalue\fP);" +.fi +.sp +The \fImatch_limit\fP parameter provides a means of preventing PCRE2 from using +up too many computing resources when processing patterns that are not going to +match, but which have a very large number of possibilities in their search +trees. The classic example is a pattern that uses nested unlimited repeats. +.P +There is an internal counter in \fBpcre2_match()\fP that is incremented each +time round its main matching loop. If this value reaches the match limit, +\fBpcre2_match()\fP returns the negative value PCRE2_ERROR_MATCHLIMIT. This has +the effect of limiting the amount of backtracking that can take place. For +patterns that are not anchored, the count restarts from zero for each position +in the subject string. This limit also applies to \fBpcre2_dfa_match()\fP, +though the counting is done in a different way. +.P +When \fBpcre2_match()\fP is called with a pattern that was successfully +processed by \fBpcre2_jit_compile()\fP, the way in which matching is executed +is entirely different. However, there is still the possibility of runaway +matching that goes on for a very long time, and so the \fImatch_limit\fP value +is also used in this case (but in a different way) to limit how long the +matching can continue. +.P +The default value for the limit can be set when PCRE2 is built; the default +default is 10 million, which handles all but the most extreme cases. A value +for the match limit may also be supplied by an item at the start of a pattern +of the form +.sp + (*LIMIT_MATCH=ddd) +.sp +where ddd is a decimal number. However, such a setting is ignored unless ddd is +less than the limit set by the caller of \fBpcre2_match()\fP or +\fBpcre2_dfa_match()\fP or, if no such limit is set, less than the default. +.sp +.nf +.B int pcre2_set_depth_limit(pcre2_match_context *\fImcontext\fP, +.B " uint32_t \fIvalue\fP);" +.fi +.sp +This parameter limits the depth of nested backtracking in \fBpcre2_match()\fP. +Each time a nested backtracking point is passed, a new memory "frame" is used +to remember the state of matching at that point. Thus, this parameter +indirectly limits the amount of memory that is used in a match. However, +because the size of each memory "frame" depends on the number of capturing +parentheses, the actual memory limit varies from pattern to pattern. This limit +was more useful in versions before 10.30, where function recursion was used for +backtracking. +.P +The depth limit is not relevant, and is ignored, when matching is done using +JIT compiled code. However, it is supported by \fBpcre2_dfa_match()\fP, which +uses it to limit the depth of nested internal recursive function calls that +implement atomic groups, lookaround assertions, and pattern recursions. This +limits, indirectly, the amount of system stack that is used. It was more useful +in versions before 10.32, when stack memory was used for local workspace +vectors for recursive function calls. From version 10.32, only local variables +are allocated on the stack and as each call uses only a few hundred bytes, even +a small stack can support quite a lot of recursion. +.P +If the depth of internal recursive function calls is great enough, local +workspace vectors are allocated on the heap from version 10.32 onwards, so the +depth limit also indirectly limits the amount of heap memory that is used. A +recursive pattern such as /(.(?2))((?1)|)/, when matched to a very long string +using \fBpcre2_dfa_match()\fP, can use a great deal of memory. However, it is +probably better to limit heap usage directly by calling +\fBpcre2_set_heap_limit()\fP. +.P +The default value for the depth limit can be set when PCRE2 is built; if it is +not, the default is set to the same value as the default for the match limit. +If the limit is exceeded, \fBpcre2_match()\fP or \fBpcre2_dfa_match()\fP +returns PCRE2_ERROR_DEPTHLIMIT. A value for the depth limit may also be +supplied by an item at the start of a pattern of the form +.sp + (*LIMIT_DEPTH=ddd) +.sp +where ddd is a decimal number. However, such a setting is ignored unless ddd is +less than the limit set by the caller of \fBpcre2_match()\fP or +\fBpcre2_dfa_match()\fP or, if no such limit is set, less than the default. +. +. +.SH "CHECKING BUILD-TIME OPTIONS" +.rs +.sp +.B int pcre2_config(uint32_t \fIwhat\fP, void *\fIwhere\fP); +.P +The function \fBpcre2_config()\fP makes it possible for a PCRE2 client to +discover which optional features have been compiled into the PCRE2 library. The +.\" HREF +\fBpcre2build\fP +.\" +documentation has more details about these optional features. +.P +The first argument for \fBpcre2_config()\fP specifies which information is +required. The second argument is a pointer to memory into which the information +is placed. If NULL is passed, the function returns the amount of memory that is +needed for the requested information. For calls that return numerical values, +the value is in bytes; when requesting these values, \fIwhere\fP should point +to appropriately aligned memory. For calls that return strings, the required +length is given in code units, not counting the terminating zero. +.P +When requesting information, the returned value from \fBpcre2_config()\fP is +non-negative on success, or the negative error code PCRE2_ERROR_BADOPTION if +the value in the first argument is not recognized. The following information is +available: +.sp + PCRE2_CONFIG_BSR +.sp +The output is a uint32_t integer whose value indicates what character +sequences the \eR escape sequence matches by default. A value of +PCRE2_BSR_UNICODE means that \eR matches any Unicode line ending sequence; a +value of PCRE2_BSR_ANYCRLF means that \eR matches only CR, LF, or CRLF. The +default can be overridden when a pattern is compiled. +.sp + PCRE2_CONFIG_COMPILED_WIDTHS +.sp +The output is a uint32_t integer whose lower bits indicate which code unit +widths were selected when PCRE2 was built. The 1-bit indicates 8-bit support, +and the 2-bit and 4-bit indicate 16-bit and 32-bit support, respectively. +.sp + PCRE2_CONFIG_DEPTHLIMIT +.sp +The output is a uint32_t integer that gives the default limit for the depth of +nested backtracking in \fBpcre2_match()\fP or the depth of nested recursions, +lookarounds, and atomic groups in \fBpcre2_dfa_match()\fP. Further details are +given with \fBpcre2_set_depth_limit()\fP above. +.sp + PCRE2_CONFIG_HEAPLIMIT +.sp +The output is a uint32_t integer that gives, in kibibytes, the default limit +for the amount of heap memory used by \fBpcre2_match()\fP or +\fBpcre2_dfa_match()\fP. Further details are given with +\fBpcre2_set_heap_limit()\fP above. +.sp + PCRE2_CONFIG_JIT +.sp +The output is a uint32_t integer that is set to one if support for just-in-time +compiling is available; otherwise it is set to zero. +.sp + PCRE2_CONFIG_JITTARGET +.sp +The \fIwhere\fP argument should point to a buffer that is at least 48 code +units long. (The exact length required can be found by calling +\fBpcre2_config()\fP with \fBwhere\fP set to NULL.) The buffer is filled with a +string that contains the name of the architecture for which the JIT compiler is +configured, for example "x86 32bit (little endian + unaligned)". If JIT support +is not available, PCRE2_ERROR_BADOPTION is returned, otherwise the number of +code units used is returned. This is the length of the string, plus one unit +for the terminating zero. +.sp + PCRE2_CONFIG_LINKSIZE +.sp +The output is a uint32_t integer that contains the number of bytes used for +internal linkage in compiled regular expressions. When PCRE2 is configured, the +value can be set to 2, 3, or 4, with the default being 2. This is the value +that is returned by \fBpcre2_config()\fP. However, when the 16-bit library is +compiled, a value of 3 is rounded up to 4, and when the 32-bit library is +compiled, internal linkages always use 4 bytes, so the configured value is not +relevant. +.P +The default value of 2 for the 8-bit and 16-bit libraries is sufficient for all +but the most massive patterns, since it allows the size of the compiled pattern +to be up to 65535 code units. Larger values allow larger regular expressions to +be compiled by those two libraries, but at the expense of slower matching. +.sp + PCRE2_CONFIG_MATCHLIMIT +.sp +The output is a uint32_t integer that gives the default match limit for +\fBpcre2_match()\fP. Further details are given with +\fBpcre2_set_match_limit()\fP above. +.sp + PCRE2_CONFIG_NEWLINE +.sp +The output is a uint32_t integer whose value specifies the default character +sequence that is recognized as meaning "newline". The values are: +.sp + PCRE2_NEWLINE_CR Carriage return (CR) + PCRE2_NEWLINE_LF Linefeed (LF) + PCRE2_NEWLINE_CRLF Carriage return, linefeed (CRLF) + PCRE2_NEWLINE_ANY Any Unicode line ending + PCRE2_NEWLINE_ANYCRLF Any of CR, LF, or CRLF + PCRE2_NEWLINE_NUL The NUL character (binary zero) +.sp +The default should normally correspond to the standard sequence for your +operating system. +.sp + PCRE2_CONFIG_NEVER_BACKSLASH_C +.sp +The output is a uint32_t integer that is set to one if the use of \eC was +permanently disabled when PCRE2 was built; otherwise it is set to zero. +.sp + PCRE2_CONFIG_PARENSLIMIT +.sp +The output is a uint32_t integer that gives the maximum depth of nesting +of parentheses (of any kind) in a pattern. This limit is imposed to cap the +amount of system stack used when a pattern is compiled. It is specified when +PCRE2 is built; the default is 250. This limit does not take into account the +stack that may already be used by the calling application. For finer control +over compilation stack usage, see \fBpcre2_set_compile_recursion_guard()\fP. +.sp + PCRE2_CONFIG_STACKRECURSE +.sp +This parameter is obsolete and should not be used in new code. The output is a +uint32_t integer that is always set to zero. +.sp + PCRE2_CONFIG_UNICODE_VERSION +.sp +The \fIwhere\fP argument should point to a buffer that is at least 24 code +units long. (The exact length required can be found by calling +\fBpcre2_config()\fP with \fBwhere\fP set to NULL.) If PCRE2 has been compiled +without Unicode support, the buffer is filled with the text "Unicode not +supported". Otherwise, the Unicode version string (for example, "8.0.0") is +inserted. The number of code units used is returned. This is the length of the +string plus one unit for the terminating zero. +.sp + PCRE2_CONFIG_UNICODE +.sp +The output is a uint32_t integer that is set to one if Unicode support is +available; otherwise it is set to zero. Unicode support implies UTF support. +.sp + PCRE2_CONFIG_VERSION +.sp +The \fIwhere\fP argument should point to a buffer that is at least 24 code +units long. (The exact length required can be found by calling +\fBpcre2_config()\fP with \fBwhere\fP set to NULL.) The buffer is filled with +the PCRE2 version string, zero-terminated. The number of code units used is +returned. This is the length of the string plus one unit for the terminating +zero. +. +. +.\" HTML +.SH "COMPILING A PATTERN" +.rs +.sp +.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);" +.sp +.B void pcre2_code_free(pcre2_code *\fIcode\fP); +.sp +.B pcre2_code *pcre2_code_copy(const pcre2_code *\fIcode\fP); +.sp +.B pcre2_code *pcre2_code_copy_with_tables(const pcre2_code *\fIcode\fP); +.fi +.P +The \fBpcre2_compile()\fP function compiles a pattern into an internal form. +The pattern is defined by a pointer to a string of code units and a length (in +code units). If the pattern is zero-terminated, the length can be specified as +PCRE2_ZERO_TERMINATED. The function returns a pointer to a block of memory that +contains the compiled pattern and related data, or NULL if an error occurred. +.P +If the compile context argument \fIccontext\fP is NULL, memory for the compiled +pattern is obtained by calling \fBmalloc()\fP. Otherwise, it is obtained from +the same memory function that was used for the compile context. The caller must +free the memory by calling \fBpcre2_code_free()\fP when it is no longer needed. +If \fBpcre2_code_free()\fP is called with a NULL argument, it returns +immediately, without doing anything. +.P +The function \fBpcre2_code_copy()\fP makes a copy of the compiled code in new +memory, using the same memory allocator as was used for the original. However, +if the code has been processed by the JIT compiler (see +.\" HTML +.\" +below), +.\" +the JIT information cannot be copied (because it is position-dependent). +The new copy can initially be used only for non-JIT matching, though it can be +passed to \fBpcre2_jit_compile()\fP if required. If \fBpcre2_code_copy()\fP is +called with a NULL argument, it returns NULL. +.P +The \fBpcre2_code_copy()\fP function provides a way for individual threads in a +multithreaded application to acquire a private copy of shared compiled code. +However, it does not make a copy of the character tables used by the compiled +pattern; the new pattern code points to the same tables as the original code. +(See +.\" HTML +.\" +"Locale Support" +.\" +below for details of these character tables.) In many applications the same +tables are used throughout, so this behaviour is appropriate. Nevertheless, +there are occasions when a copy of a compiled pattern and the relevant tables +are needed. The \fBpcre2_code_copy_with_tables()\fP provides this facility. +Copies of both the code and the tables are made, with the new code pointing to +the new tables. The memory for the new tables is automatically freed when +\fBpcre2_code_free()\fP is called for the new copy of the compiled code. If +\fBpcre2_code_copy_withy_tables()\fP is called with a NULL argument, it returns +NULL. +.P +NOTE: When one of the matching functions is called, pointers to the compiled +pattern and the subject string are set in the match data block so that they can +be referenced by the substring extraction functions. After running a match, you +must not free a compiled pattern (or a subject string) until after all +operations on the +.\" HTML +.\" +match data block +.\" +have taken place. +.P +The \fIoptions\fP argument for \fBpcre2_compile()\fP contains various bit +settings that affect the compilation. It should be zero if no options are +required. The available options are described below. Some of them (in +particular, those that are compatible with Perl, but some others as well) can +also be set and unset from within the pattern (see the detailed description in +the +.\" HREF +\fBpcre2pattern\fP +.\" +documentation). +.P +For those options that can be different in different parts of the pattern, the +contents of the \fIoptions\fP argument specifies their settings at the start of +compilation. The PCRE2_ANCHORED, PCRE2_ENDANCHORED, and PCRE2_NO_UTF_CHECK +options can be set at the time of matching as well as at compile time. +.P +Other, less frequently required compile-time parameters (for example, the +newline setting) can be provided in a compile context (as described +.\" HTML +.\" +above). +.\" +.P +If \fIerrorcode\fP or \fIerroroffset\fP is NULL, \fBpcre2_compile()\fP returns +NULL immediately. Otherwise, the variables to which these point are set to an +error code and an offset (number of code units) within the pattern, +respectively, when \fBpcre2_compile()\fP returns NULL because a compilation +error has occurred. The values are not defined when compilation is successful +and \fBpcre2_compile()\fP returns a non-NULL value. +.P +There are nearly 100 positive error codes that \fBpcre2_compile()\fP may return +if it finds an error in the pattern. There are also some negative error codes +that are used for invalid UTF strings. These are the same as given by +\fBpcre2_match()\fP and \fBpcre2_dfa_match()\fP, and are described in the +.\" HREF +\fBpcre2unicode\fP +.\" +page. There is no separate documentation for the positive error codes, because +the textual error messages that are obtained by calling the +\fBpcre2_get_error_message()\fP function (see "Obtaining a textual error +message" +.\" HTML +.\" +below) +.\" +should be self-explanatory. Macro names starting with PCRE2_ERROR_ are defined +for both positive and negative error codes in \fBpcre2.h\fP. +.P +The value returned in \fIerroroffset\fP is an indication of where in the +pattern the error occurred. It is not necessarily the furthest point in the +pattern that was read. For example, after the error "lookbehind assertion is +not fixed length", the error offset points to the start of the failing +assertion. For an invalid UTF-8 or UTF-16 string, the offset is that of the +first code unit of the failing character. +.P +Some errors are not detected until the whole pattern has been scanned; in these +cases, the offset passed back is the length of the pattern. Note that the +offset is in code units, not characters, even in a UTF mode. It may sometimes +point into the middle of a UTF-8 or UTF-16 character. +.P +This code fragment shows a typical straightforward call to +\fBpcre2_compile()\fP: +.sp + pcre2_code *re; + PCRE2_SIZE erroffset; + int errorcode; + re = pcre2_compile( + "^A.*Z", /* the pattern */ + PCRE2_ZERO_TERMINATED, /* the pattern is zero-terminated */ + 0, /* default options */ + &errorcode, /* for error code */ + &erroffset, /* for error offset */ + NULL); /* no compile context */ +.sp +The following names for option bits are defined in the \fBpcre2.h\fP header +file: +.sp + PCRE2_ANCHORED +.sp +If this bit is set, the pattern is forced to be "anchored", that is, it is +constrained to match only at the first matching point in the string that is +being searched (the "subject string"). This effect can also be achieved by +appropriate constructs in the pattern itself, which is the only way to do it in +Perl. +.sp + PCRE2_ALLOW_EMPTY_CLASS +.sp +By default, for compatibility with Perl, a closing square bracket that +immediately follows an opening one is treated as a data character for the +class. When PCRE2_ALLOW_EMPTY_CLASS is set, it terminates the class, which +therefore contains no characters and so can never match. +.sp + PCRE2_ALT_BSUX +.sp +This option request alternative handling of three escape sequences, which +makes PCRE2's behaviour more like ECMAscript (aka JavaScript). When it is set: +.P +(1) \eU matches an upper case "U" character; by default \eU causes a compile +time error (Perl uses \eU to upper case subsequent characters). +.P +(2) \eu matches a lower case "u" character unless it is followed by four +hexadecimal digits, in which case the hexadecimal number defines the code point +to match. By default, \eu causes a compile time error (Perl uses it to upper +case the following character). +.P +(3) \ex matches a lower case "x" character unless it is followed by two +hexadecimal digits, in which case the hexadecimal number defines the code point +to match. By default, as in Perl, a hexadecimal number is always expected after +\ex, but it may have zero, one, or two digits (so, for example, \exz matches a +binary zero character followed by z). +.sp + PCRE2_ALT_CIRCUMFLEX +.sp +In multiline mode (when PCRE2_MULTILINE is set), the circumflex metacharacter +matches at the start of the subject (unless PCRE2_NOTBOL is set), and also +after any internal newline. However, it does not match after a newline at the +end of the subject, for compatibility with Perl. If you want a multiline +circumflex also to match after a terminating newline, you must set +PCRE2_ALT_CIRCUMFLEX. +.sp + PCRE2_ALT_VERBNAMES +.sp +By default, for compatibility with Perl, the name in any verb sequence such as +(*MARK:NAME) is any sequence of characters that does not include a closing +parenthesis. The name is not processed in any way, and it is not possible to +include a closing parenthesis in the name. However, if the PCRE2_ALT_VERBNAMES +option is set, normal backslash processing is applied to verb names and only an +unescaped closing parenthesis terminates the name. A closing parenthesis can be +included in a name either as \e) or between \eQ and \eE. If the PCRE2_EXTENDED +or PCRE2_EXTENDED_MORE option is set with PCRE2_ALT_VERBNAMES, unescaped +whitespace in verb names is skipped and #-comments are recognized, exactly as +in the rest of the pattern. +.sp + PCRE2_AUTO_CALLOUT +.sp +If this bit is set, \fBpcre2_compile()\fP automatically inserts callout items, +all with number 255, before each pattern item, except immediately before or +after an explicit callout in the pattern. For discussion of the callout +facility, see the +.\" HREF +\fBpcre2callout\fP +.\" +documentation. +.sp + PCRE2_CASELESS +.sp +If this bit is set, letters in the pattern match both upper and lower case +letters in the subject. It is equivalent to Perl's /i option, and it can be +changed within a pattern by a (?i) option setting. If PCRE2_UTF is set, Unicode +properties are used for all characters with more than one other case, and for +all characters whose code points are greater than U+007F. For lower valued +characters with only one other case, a lookup table is used for speed. When +PCRE2_UTF is not set, a lookup table is used for all code points less than 256, +and higher code points (available only in 16-bit or 32-bit mode) are treated as +not having another case. +.sp + PCRE2_DOLLAR_ENDONLY +.sp +If this bit is set, a dollar metacharacter in the pattern matches only at the +end of the subject string. Without this option, a dollar also matches +immediately before a newline at the end of the string (but not before any other +newlines). The PCRE2_DOLLAR_ENDONLY option is ignored if PCRE2_MULTILINE is +set. There is no equivalent to this option in Perl, and no way to set it within +a pattern. +.sp + PCRE2_DOTALL +.sp +If this bit is set, a dot metacharacter in the pattern matches any character, +including one that indicates a newline. However, it only ever matches one +character, even if newlines are coded as CRLF. Without this option, a dot does +not match when the current position in the subject is at a newline. This option +is equivalent to Perl's /s option, and it can be changed within a pattern by a +(?s) option setting. A negative class such as [^a] always matches newline +characters, and the \eN escape sequence always matches a non-newline character, +independent of the setting of PCRE2_DOTALL. +.sp + PCRE2_DUPNAMES +.sp +If this bit is set, names used to identify capturing subpatterns need not be +unique. This can be helpful for certain types of pattern when it is known that +only one instance of the named subpattern can ever be matched. There are more +details of named subpatterns below; see also the +.\" HREF +\fBpcre2pattern\fP +.\" +documentation. +.sp + PCRE2_ENDANCHORED +.sp +If this bit is set, the end of any pattern match must be right at the end of +the string being searched (the "subject string"). If the pattern match +succeeds by reaching (*ACCEPT), but does not reach the end of the subject, the +match fails at the current starting point. For unanchored patterns, a new match +is then tried at the next starting point. However, if the match succeeds by +reaching the end of the pattern, but not the end of the subject, backtracking +occurs and an alternative match may be found. Consider these two patterns: +.sp + .(*ACCEPT)|.. + .|.. +.sp +If matched against "abc" with PCRE2_ENDANCHORED set, the first matches "c" +whereas the second matches "bc". The effect of PCRE2_ENDANCHORED can also be +achieved by appropriate constructs in the pattern itself, which is the only way +to do it in Perl. +.P +For DFA matching with \fBpcre2_dfa_match()\fP, PCRE2_ENDANCHORED applies only +to the first (that is, the longest) matched string. Other parallel matches, +which are necessarily substrings of the first one, must obviously end before +the end of the subject. +.sp + PCRE2_EXTENDED +.sp +If this bit is set, most white space characters in the pattern are totally +ignored except when escaped or inside a character class. However, white space +is not allowed within sequences such as (?> that introduce various +parenthesized subpatterns, nor within numerical quantifiers such as {1,3}. +Ignorable white space is permitted between an item and a following quantifier +and between a quantifier and a following + that indicates possessiveness. +PCRE2_EXTENDED is equivalent to Perl's /x option, and it can be changed within +a pattern by a (?x) option setting. +.P +When PCRE2 is compiled without Unicode support, PCRE2_EXTENDED recognizes as +white space only those characters with code points less than 256 that are +flagged as white space in its low-character table. The table is normally +created by +.\" HREF +\fBpcre2_maketables()\fP, +.\" +which uses the \fBisspace()\fP function to identify space characters. In most +ASCII environments, the relevant characters are those with code points 0x0009 +(tab), 0x000A (linefeed), 0x000B (vertical tab), 0x000C (formfeed), 0x000D +(carriage return), and 0x0020 (space). +.P +When PCRE2 is compiled with Unicode support, in addition to these characters, +five more Unicode "Pattern White Space" characters are recognized by +PCRE2_EXTENDED. These are U+0085 (next line), U+200E (left-to-right mark), +U+200F (right-to-left mark), U+2028 (line separator), and U+2029 (paragraph +separator). This set of characters is the same as recognized by Perl's /x +option. Note that the horizontal and vertical space characters that are matched +by the \eh and \ev escapes in patterns are a much bigger set. +.P +As well as ignoring most white space, PCRE2_EXTENDED also causes characters +between an unescaped # outside a character class and the next newline, +inclusive, to be ignored, which makes it possible to include comments inside +complicated patterns. Note that the end of this type of comment is a literal +newline sequence in the pattern; escape sequences that happen to represent a +newline do not count. +.P +Which characters are interpreted as newlines can be specified by a setting in +the compile context that is passed to \fBpcre2_compile()\fP or by a special +sequence at the start of the pattern, as described in the section entitled +.\" HTML +.\" +"Newline conventions" +.\" +in the \fBpcre2pattern\fP documentation. A default is defined when PCRE2 is +built. +.sp + PCRE2_EXTENDED_MORE +.sp +This option has the effect of PCRE2_EXTENDED, but, in addition, unescaped space +and horizontal tab characters are ignored inside a character class. Note: only +these two characters are ignored, not the full set of pattern white space +characters that are ignored outside a character class. PCRE2_EXTENDED_MORE is +equivalent to Perl's /xx option, and it can be changed within a pattern by a +(?xx) option setting. +.sp + PCRE2_FIRSTLINE +.sp +If this option is set, the start of an unanchored pattern match must be before +or at the first newline in the subject string following the start of matching, +though the matched text may continue over the newline. If \fIstartoffset\fP is +non-zero, the limiting newline is not necessarily the first newline in the +subject. For example, if the subject string is "abc\enxyz" (where \en +represents a single-character newline) a pattern match for "yz" succeeds with +PCRE2_FIRSTLINE if \fIstartoffset\fP is greater than 3. See also +PCRE2_USE_OFFSET_LIMIT, which provides a more general limiting facility. If +PCRE2_FIRSTLINE is set with an offset limit, a match must occur in the first +line and also within the offset limit. In other words, whichever limit comes +first is used. +.sp + PCRE2_LITERAL +.sp +If this option is set, all meta-characters in the pattern are disabled, and it +is treated as a literal string. Matching literal strings with a regular +expression engine is not the most efficient way of doing it. If you are doing a +lot of literal matching and are worried about efficiency, you should consider +using other approaches. The only other main options that are allowed with +PCRE2_LITERAL are: PCRE2_ANCHORED, PCRE2_ENDANCHORED, PCRE2_AUTO_CALLOUT, +PCRE2_CASELESS, PCRE2_FIRSTLINE, PCRE2_NO_START_OPTIMIZE, PCRE2_NO_UTF_CHECK, +PCRE2_UTF, and PCRE2_USE_OFFSET_LIMIT. The extra options PCRE2_EXTRA_MATCH_LINE +and PCRE2_EXTRA_MATCH_WORD are also supported. Any other options cause an +error. +.sp + PCRE2_MATCH_UNSET_BACKREF +.sp +If this option is set, a backreference to an unset subpattern group matches an +empty string (by default this causes the current matching alternative to fail). +A pattern such as (\e1)(a) succeeds when this option is set (assuming it can +find an "a" in the subject), whereas it fails by default, for Perl +compatibility. Setting this option makes PCRE2 behave more like ECMAscript (aka +JavaScript). +.sp + PCRE2_MULTILINE +.sp +By default, for the purposes of matching "start of line" and "end of line", +PCRE2 treats the subject string as consisting of a single line of characters, +even if it actually contains newlines. The "start of line" metacharacter (^) +matches only at the start of the string, and the "end of line" metacharacter +($) matches only at the end of the string, or before a terminating newline +(except when PCRE2_DOLLAR_ENDONLY is set). Note, however, that unless +PCRE2_DOTALL is set, the "any character" metacharacter (.) does not match at a +newline. This behaviour (for ^, $, and dot) is the same as Perl. +.P +When PCRE2_MULTILINE it is set, the "start of line" and "end of line" +constructs match immediately following or immediately before internal newlines +in the subject string, respectively, as well as at the very start and end. This +is equivalent to Perl's /m option, and it can be changed within a pattern by a +(?m) option setting. Note that the "start of line" metacharacter does not match +after a newline at the end of the subject, for compatibility with Perl. +However, you can change this by setting the PCRE2_ALT_CIRCUMFLEX option. If +there are no newlines in a subject string, or no occurrences of ^ or $ in a +pattern, setting PCRE2_MULTILINE has no effect. +.sp + PCRE2_NEVER_BACKSLASH_C +.sp +This option locks out the use of \eC in the pattern that is being compiled. +This escape can cause unpredictable behaviour in UTF-8 or UTF-16 modes, because +it may leave the current matching point in the middle of a multi-code-unit +character. This option may be useful in applications that process patterns from +external sources. Note that there is also a build-time option that permanently +locks out the use of \eC. +.sp + PCRE2_NEVER_UCP +.sp +This option locks out the use of Unicode properties for handling \eB, \eb, \eD, +\ed, \eS, \es, \eW, \ew, and some of the POSIX character classes, as described +for the PCRE2_UCP option below. In particular, it prevents the creator of the +pattern from enabling this facility by starting the pattern with (*UCP). This +option may be useful in applications that process patterns from external +sources. The option combination PCRE_UCP and PCRE_NEVER_UCP causes an error. +.sp + PCRE2_NEVER_UTF +.sp +This option locks out interpretation of the pattern as UTF-8, UTF-16, or +UTF-32, depending on which library is in use. In particular, it prevents the +creator of the pattern from switching to UTF interpretation by starting the +pattern with (*UTF). This option may be useful in applications that process +patterns from external sources. The combination of PCRE2_UTF and +PCRE2_NEVER_UTF causes an error. +.sp + PCRE2_NO_AUTO_CAPTURE +.sp +If this option is set, it disables the use of numbered capturing parentheses in +the pattern. Any opening parenthesis that is not followed by ? behaves as if it +were followed by ?: but named parentheses can still be used for capturing (and +they acquire numbers in the usual way). This is the same as Perl's /n option. +Note that, when this option is set, references to capturing groups +(backreferences or recursion/subroutine calls) may only refer to named groups, +though the reference can be by name or by number. +.sp + PCRE2_NO_AUTO_POSSESS +.sp +If this option is set, it disables "auto-possessification", which is an +optimization that, for example, turns a+b into a++b in order to avoid +backtracks into a+ that can never be successful. However, if callouts are in +use, auto-possessification means that some callouts are never taken. You can +set this option if you want the matching functions to do a full unoptimized +search and run all the callouts, but it is mainly provided for testing +purposes. +.sp + PCRE2_NO_DOTSTAR_ANCHOR +.sp +If this option is set, it disables an optimization that is applied when .* is +the first significant item in a top-level branch of a pattern, and all the +other branches also start with .* or with \eA or \eG or ^. The optimization is +automatically disabled for .* if it is inside an atomic group or a capturing +group that is the subject of a backreference, or if the pattern contains +(*PRUNE) or (*SKIP). When the optimization is not disabled, such a pattern is +automatically anchored if PCRE2_DOTALL is set for all the .* items and +PCRE2_MULTILINE is not set for any ^ items. Otherwise, the fact that any match +must start either at the start of the subject or following a newline is +remembered. Like other optimizations, this can cause callouts to be skipped. +.sp + PCRE2_NO_START_OPTIMIZE +.sp +This is an option whose main effect is at matching time. It does not change +what \fBpcre2_compile()\fP generates, but it does affect the output of the JIT +compiler. +.P +There are a number of optimizations that may occur at the start of a match, in +order to speed up the process. For example, if it is known that an unanchored +match must start with a specific code unit value, the matching code searches +the subject for that value, and fails immediately if it cannot find it, without +actually running the main matching function. This means that a special item +such as (*COMMIT) at the start of a pattern is not considered until after a +suitable starting point for the match has been found. Also, when callouts or +(*MARK) items are in use, these "start-up" optimizations can cause them to be +skipped if the pattern is never actually used. The start-up optimizations are +in effect a pre-scan of the subject that takes place before the pattern is run. +.P +The PCRE2_NO_START_OPTIMIZE option disables the start-up optimizations, +possibly causing performance to suffer, but ensuring that in cases where the +result is "no match", the callouts do occur, and that items such as (*COMMIT) +and (*MARK) are considered at every possible starting position in the subject +string. +.P +Setting PCRE2_NO_START_OPTIMIZE may change the outcome of a matching operation. +Consider the pattern +.sp + (*COMMIT)ABC +.sp +When this is compiled, PCRE2 records the fact that a match must start with the +character "A". Suppose the subject string is "DEFABC". The start-up +optimization scans along the subject, finds "A" and runs the first match +attempt from there. The (*COMMIT) item means that the pattern must match the +current starting position, which in this case, it does. However, if the same +match is run with PCRE2_NO_START_OPTIMIZE set, the initial scan along the +subject string does not happen. The first match attempt is run starting from +"D" and when this fails, (*COMMIT) prevents any further matches being tried, so +the overall result is "no match". +.P +There are also other start-up optimizations. For example, a minimum length for +the subject may be recorded. Consider the pattern +.sp + (*MARK:A)(X|Y) +.sp +The minimum length for a match is one character. If the subject is "ABC", there +will be attempts to match "ABC", "BC", and "C". An attempt to match an empty +string at the end of the subject does not take place, because PCRE2 knows that +the subject is now too short, and so the (*MARK) is never encountered. In this +case, the optimization does not affect the overall match result, which is still +"no match", but it does affect the auxiliary information that is returned. +.sp + PCRE2_NO_UTF_CHECK +.sp +When PCRE2_UTF is set, the validity of the pattern as a UTF string is +automatically checked. There are discussions about the validity of +.\" HTML +.\" +UTF-8 strings, +.\" +.\" HTML +.\" +UTF-16 strings, +.\" +and +.\" HTML +.\" +UTF-32 strings +.\" +in the +.\" HREF +\fBpcre2unicode\fP +.\" +document. If an invalid UTF sequence is found, \fBpcre2_compile()\fP returns a +negative error code. +.P +If you know that your pattern is a valid UTF string, and you want to skip this +check for performance reasons, you can set the PCRE2_NO_UTF_CHECK option. When +it is set, the effect of passing an invalid UTF string as a pattern is +undefined. It may cause your program to crash or loop. +.P +Note that this option can also be passed to \fBpcre2_match()\fP and +\fBpcre_dfa_match()\fP, to suppress UTF validity checking of the subject +string. +.P +Note also that setting PCRE2_NO_UTF_CHECK at compile time does not disable the +error that is given if an escape sequence for an invalid Unicode code point is +encountered in the pattern. In particular, the so-called "surrogate" code +points (0xd800 to 0xdfff) are invalid. If you want to allow escape sequences +such as \ex{d800} you can set the PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES extra +option, as described in the section entitled "Extra compile options" +.\" HTML +.\" +below. +.\" +However, this is possible only in UTF-8 and UTF-32 modes, because these values +are not representable in UTF-16. +.sp + PCRE2_UCP +.sp +This option changes the way PCRE2 processes \eB, \eb, \eD, \ed, \eS, \es, \eW, +\ew, and some of the POSIX character classes. By default, only ASCII characters +are recognized, but if PCRE2_UCP is set, Unicode properties are used instead to +classify characters. More details are given in the section on +.\" HTML +.\" +generic character types +.\" +in the +.\" HREF +\fBpcre2pattern\fP +.\" +page. If you set PCRE2_UCP, matching one of the items it affects takes much +longer. The option is available only if PCRE2 has been compiled with Unicode +support (which is the default). +.sp + PCRE2_UNGREEDY +.sp +This option inverts the "greediness" of the quantifiers so that they are not +greedy by default, but become greedy if followed by "?". It is not compatible +with Perl. It can also be set by a (?U) option setting within the pattern. +.sp + PCRE2_USE_OFFSET_LIMIT +.sp +This option must be set for \fBpcre2_compile()\fP if +\fBpcre2_set_offset_limit()\fP is going to be used to set a non-default offset +limit in a match context for matches that use this pattern. An error is +generated if an offset limit is set without this option. For more details, see +the description of \fBpcre2_set_offset_limit()\fP in the +.\" HTML +.\" +section +.\" +that describes match contexts. See also the PCRE2_FIRSTLINE +option above. +.sp + PCRE2_UTF +.sp +This option causes PCRE2 to regard both the pattern and the subject strings +that are subsequently processed as strings of UTF characters instead of +single-code-unit strings. It is available when PCRE2 is built to include +Unicode support (which is the default). If Unicode support is not available, +the use of this option provokes an error. Details of how PCRE2_UTF changes the +behaviour of PCRE2 are given in the +.\" HREF +\fBpcre2unicode\fP +.\" +page. In particular, note that it changes the way PCRE2_CASELESS handles +characters with code points greater than 127. +. +. +.\" HTML +.SS "Extra compile options" +.rs +.sp +Unlike the main compile-time options, the extra options are not saved with the +compiled pattern. The option bits that can be set in a compile context by +calling the \fBpcre2_set_compile_extra_options()\fP function are as follows: +.sp + PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES +.sp +This option applies when compiling a pattern in UTF-8 or UTF-32 mode. It is +forbidden in UTF-16 mode, and ignored in non-UTF modes. Unicode "surrogate" +code points in the range 0xd800 to 0xdfff are used in pairs in UTF-16 to encode +code points with values in the range 0x10000 to 0x10ffff. The surrogates cannot +therefore be represented in UTF-16. They can be represented in UTF-8 and +UTF-32, but are defined as invalid code points, and cause errors if encountered +in a UTF-8 or UTF-32 string that is being checked for validity by PCRE2. +.P +These values also cause errors if encountered in escape sequences such as +\ex{d912} within a pattern. However, it seems that some applications, when +using PCRE2 to check for unwanted characters in UTF-8 strings, explicitly test +for the surrogates using escape sequences. The PCRE2_NO_UTF_CHECK option does +not disable the error that occurs, because it applies only to the testing of +input strings for UTF validity. +.P +If the extra option PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES is set, surrogate code +point values in UTF-8 and UTF-32 patterns no longer provoke errors and are +incorporated in the compiled pattern. However, they can only match subject +characters if the matching function is called with PCRE2_NO_UTF_CHECK set. +.sp + PCRE2_EXTRA_BAD_ESCAPE_IS_LITERAL +.sp +This is a dangerous option. Use with care. By default, an unrecognized escape +such as \ej or a malformed one such as \ex{2z} causes a compile-time error when +detected by \fBpcre2_compile()\fP. Perl is somewhat inconsistent in handling +such items: for example, \ej is treated as a literal "j", and non-hexadecimal +digits in \ex{} are just ignored, though warnings are given in both cases if +Perl's warning switch is enabled. However, a malformed octal number after \eo{ +always causes an error in Perl. +.P +If the PCRE2_EXTRA_BAD_ESCAPE_IS_LITERAL extra option is passed to +\fBpcre2_compile()\fP, all unrecognized or erroneous escape sequences are +treated as single-character escapes. For example, \ej is a literal "j" and +\ex{2z} is treated as the literal string "x{2z}". Setting this option means +that typos in patterns may go undetected and have unexpected results. This is a +dangerous option. Use with care. +.sp + PCRE2_EXTRA_MATCH_LINE +.sp +This option is provided for use by the \fB-x\fP option of \fBpcre2grep\fP. It +causes the pattern only to match complete lines. This is achieved by +automatically inserting the code for "^(?:" at the start of the compiled +pattern and ")$" at the end. Thus, when PCRE2_MULTILINE is set, the matched +line may be in the middle of the subject string. This option can be used with +PCRE2_LITERAL. +.sp + PCRE2_EXTRA_MATCH_WORD +.sp +This option is provided for use by the \fB-w\fP option of \fBpcre2grep\fP. It +causes the pattern only to match strings that have a word boundary at the start +and the end. This is achieved by automatically inserting the code for "\eb(?:" +at the start of the compiled pattern and ")\eb" at the end. The option may be +used with PCRE2_LITERAL. However, it is ignored if PCRE2_EXTRA_MATCH_LINE is +also set. +. +. +.\" HTML +.SH "JUST-IN-TIME (JIT) COMPILATION" +.rs +.sp +.nf +.B int pcre2_jit_compile(pcre2_code *\fIcode\fP, uint32_t \fIoptions\fP); +.sp +.B int pcre2_jit_match(const pcre2_code *\fIcode\fP, PCRE2_SPTR \fIsubject\fP, +.B " PCRE2_SIZE \fIlength\fP, PCRE2_SIZE \fIstartoffset\fP," +.B " uint32_t \fIoptions\fP, pcre2_match_data *\fImatch_data\fP," +.B " pcre2_match_context *\fImcontext\fP);" +.sp +.B void pcre2_jit_free_unused_memory(pcre2_general_context *\fIgcontext\fP); +.sp +.B pcre2_jit_stack *pcre2_jit_stack_create(PCRE2_SIZE \fIstartsize\fP, +.B " PCRE2_SIZE \fImaxsize\fP, pcre2_general_context *\fIgcontext\fP);" +.sp +.B void pcre2_jit_stack_assign(pcre2_match_context *\fImcontext\fP, +.B " pcre2_jit_callback \fIcallback_function\fP, void *\fIcallback_data\fP);" +.sp +.B void pcre2_jit_stack_free(pcre2_jit_stack *\fIjit_stack\fP); +.fi +.P +These functions provide support for JIT compilation, which, if the just-in-time +compiler is available, further processes a compiled pattern into machine code +that executes much faster than the \fBpcre2_match()\fP interpretive matching +function. Full details are given in the +.\" HREF +\fBpcre2jit\fP +.\" +documentation. +.P +JIT compilation is a heavyweight optimization. It can take some time for +patterns to be analyzed, and for one-off matches and simple patterns the +benefit of faster execution might be offset by a much slower compilation time. +Most (but not all) patterns can be optimized by the JIT compiler. +. +. +.\" HTML +.SH "LOCALE SUPPORT" +.rs +.sp +PCRE2 handles caseless matching, and determines whether characters are letters, +digits, or whatever, by reference to a set of tables, indexed by character code +point. This applies only to characters whose code points are less than 256. By +default, higher-valued code points never match escapes such as \ew or \ed. +However, if PCRE2 is built with Unicode support, all characters can be tested +with \ep and \eP, or, alternatively, the PCRE2_UCP option can be set when a +pattern is compiled; this causes \ew and friends to use Unicode property +support instead of the built-in tables. +.P +The use of locales with Unicode is discouraged. If you are handling characters +with code points greater than 128, you should either use Unicode support, or +use locales, but not try to mix the two. +.P +PCRE2 contains an internal set of character tables that are used by default. +These are sufficient for many applications. Normally, the internal tables +recognize only ASCII characters. However, when PCRE2 is built, it is possible +to cause the internal tables to be rebuilt in the default "C" locale of the +local system, which may cause them to be different. +.P +The internal tables can be overridden by tables supplied by the application +that calls PCRE2. These may be created in a different locale from the default. +As more and more applications change to using Unicode, the need for this locale +support is expected to die away. +.P +External tables are built by calling the \fBpcre2_maketables()\fP function, in +the relevant locale. The result can be passed to \fBpcre2_compile()\fP as often +as necessary, by creating a compile context and calling +\fBpcre2_set_character_tables()\fP to set the tables pointer therein. For +example, to build and use tables that are appropriate for the French locale +(where accented characters with values greater than 128 are treated as +letters), the following code could be used: +.sp + setlocale(LC_CTYPE, "fr_FR"); + tables = pcre2_maketables(NULL); + ccontext = pcre2_compile_context_create(NULL); + pcre2_set_character_tables(ccontext, tables); + re = pcre2_compile(..., ccontext); +.sp +The locale name "fr_FR" is used on Linux and other Unix-like systems; if you +are using Windows, the name for the French locale is "french". It is the +caller's responsibility to ensure that the memory containing the tables remains +available for as long as it is needed. +.P +The pointer that is passed (via the compile context) to \fBpcre2_compile()\fP +is saved with the compiled pattern, and the same tables are used by +\fBpcre2_match()\fP and \fBpcre_dfa_match()\fP. Thus, for any single pattern, +compilation and matching both happen in the same locale, but different patterns +can be processed in different locales. +. +. +.\" HTML +.SH "INFORMATION ABOUT A COMPILED PATTERN" +.rs +.sp +.nf +.B int pcre2_pattern_info(const pcre2 *\fIcode\fP, uint32_t \fIwhat\fP, void *\fIwhere\fP); +.fi +.P +The \fBpcre2_pattern_info()\fP function returns general information about a +compiled pattern. For information about callouts, see the +.\" HTML +.\" +next section. +.\" +The first argument for \fBpcre2_pattern_info()\fP is a pointer to the compiled +pattern. The second argument specifies which piece of information is required, +and the third argument is a pointer to a variable to receive the data. If the +third argument is NULL, the first argument is ignored, and the function returns +the size in bytes of the variable that is required for the information +requested. Otherwise, the yield of the function is zero for success, or one of +the following negative numbers: +.sp + PCRE2_ERROR_NULL the argument \fIcode\fP was NULL + PCRE2_ERROR_BADMAGIC the "magic number" was not found + PCRE2_ERROR_BADOPTION the value of \fIwhat\fP was invalid + PCRE2_ERROR_UNSET the requested field is not set +.sp +The "magic number" is placed at the start of each compiled pattern as an simple +check against passing an arbitrary memory pointer. Here is a typical call of +\fBpcre2_pattern_info()\fP, to obtain the length of the compiled pattern: +.sp + int rc; + size_t length; + rc = pcre2_pattern_info( + re, /* result of pcre2_compile() */ + PCRE2_INFO_SIZE, /* what is required */ + &length); /* where to put the data */ +.sp +The possible values for the second argument are defined in \fBpcre2.h\fP, and +are as follows: +.sp + PCRE2_INFO_ALLOPTIONS + PCRE2_INFO_ARGOPTIONS + PCRE2_INFO_EXTRAOPTIONS +.sp +Return copies of the pattern's options. The third argument should point to a +\fBuint32_t\fP variable. PCRE2_INFO_ARGOPTIONS returns exactly the options that +were passed to \fBpcre2_compile()\fP, whereas PCRE2_INFO_ALLOPTIONS returns +the compile options as modified by any top-level (*XXX) option settings such as +(*UTF) at the start of the pattern itself. PCRE2_INFO_EXTRAOPTIONS returns the +extra options that were set in the compile context by calling the +pcre2_set_compile_extra_options() function. +.P +For example, if the pattern /(*UTF)abc/ is compiled with the PCRE2_EXTENDED +option, the result for PCRE2_INFO_ALLOPTIONS is PCRE2_EXTENDED and PCRE2_UTF. +Option settings such as (?i) that can change within a pattern do not affect the +result of PCRE2_INFO_ALLOPTIONS, even if they appear right at the start of the +pattern. (This was different in some earlier releases.) +.P +A pattern compiled without PCRE2_ANCHORED is automatically anchored by PCRE2 if +the first significant item in every top-level branch is one of the following: +.sp + ^ unless PCRE2_MULTILINE is set + \eA always + \eG always + .* sometimes - see below +.sp +When .* is the first significant item, anchoring is possible only when all the +following are true: +.sp + .* is not in an atomic group +.\" JOIN + .* is not in a capturing group that is the subject + of a backreference + PCRE2_DOTALL is in force for .* + Neither (*PRUNE) nor (*SKIP) appears in the pattern + PCRE2_NO_DOTSTAR_ANCHOR is not set +.sp +For patterns that are auto-anchored, the PCRE2_ANCHORED bit is set in the +options returned for PCRE2_INFO_ALLOPTIONS. +.sp + PCRE2_INFO_BACKREFMAX +.sp +Return the number of the highest backreference in the pattern. The third +argument should point to an \fBuint32_t\fP variable. Named subpatterns acquire +numbers as well as names, and these count towards the highest backreference. +Backreferences such as \e4 or \eg{12} match the captured characters of the +given group, but in addition, the check that a capturing group is set in a +conditional subpattern such as (?(3)a|b) is also a backreference. Zero is +returned if there are no backreferences. +.sp + PCRE2_INFO_BSR +.sp +The output is a uint32_t integer whose value indicates what character sequences +the \eR escape sequence matches. A value of PCRE2_BSR_UNICODE means that \eR +matches any Unicode line ending sequence; a value of PCRE2_BSR_ANYCRLF means +that \eR matches only CR, LF, or CRLF. +.sp + PCRE2_INFO_CAPTURECOUNT +.sp +Return the highest capturing subpattern number in the pattern. In patterns +where (?| is not used, this is also the total number of capturing subpatterns. +The third argument should point to an \fBuint32_t\fP variable. +.sp + PCRE2_INFO_DEPTHLIMIT +.sp +If the pattern set a backtracking depth limit by including an item of the form +(*LIMIT_DEPTH=nnnn) at the start, the value is returned. The third argument +should point to a uint32_t integer. If no such value has been set, the call to +\fBpcre2_pattern_info()\fP returns the error PCRE2_ERROR_UNSET. Note that this +limit will only be used during matching if it is less than the limit set or +defaulted by the caller of the match function. +.sp + PCRE2_INFO_FIRSTBITMAP +.sp +In the absence of a single first code unit for a non-anchored pattern, +\fBpcre2_compile()\fP may construct a 256-bit table that defines a fixed set of +values for the first code unit in any match. For example, a pattern that starts +with [abc] results in a table with three bits set. When code unit values +greater than 255 are supported, the flag bit for 255 means "any code unit of +value 255 or above". If such a table was constructed, a pointer to it is +returned. Otherwise NULL is returned. The third argument should point to a +\fBconst uint8_t *\fP variable. +.sp + PCRE2_INFO_FIRSTCODETYPE +.sp +Return information about the first code unit of any matched string, for a +non-anchored pattern. The third argument should point to an \fBuint32_t\fP +variable. If there is a fixed first value, for example, the letter "c" from a +pattern such as (cat|cow|coyote), 1 is returned, and the value can be retrieved +using PCRE2_INFO_FIRSTCODEUNIT. If there is no fixed first value, but it is +known that a match can occur only at the start of the subject or following a +newline in the subject, 2 is returned. Otherwise, and for anchored patterns, 0 +is returned. +.sp + PCRE2_INFO_FIRSTCODEUNIT +.sp +Return the value of the first code unit of any matched string for a pattern +where PCRE2_INFO_FIRSTCODETYPE returns 1; otherwise return 0. The third +argument should point to an \fBuint32_t\fP variable. In the 8-bit library, the +value is always less than 256. In the 16-bit library the value can be up to +0xffff. In the 32-bit library in UTF-32 mode the value can be up to 0x10ffff, +and up to 0xffffffff when not using UTF-32 mode. +.sp + PCRE2_INFO_FRAMESIZE +.sp +Return the size (in bytes) of the data frames that are used to remember +backtracking positions when the pattern is processed by \fBpcre2_match()\fP +without the use of JIT. The third argument should point to a \fBsize_t\fP +variable. The frame size depends on the number of capturing parentheses in the +pattern. Each additional capturing group adds two PCRE2_SIZE variables. +.sp + PCRE2_INFO_HASBACKSLASHC +.sp +Return 1 if the pattern contains any instances of \eC, otherwise 0. The third +argument should point to an \fBuint32_t\fP variable. +.sp + PCRE2_INFO_HASCRORLF +.sp +Return 1 if the pattern contains any explicit matches for CR or LF characters, +otherwise 0. The third argument should point to an \fBuint32_t\fP variable. An +explicit match is either a literal CR or LF character, or \er or \en or one of +the equivalent hexadecimal or octal escape sequences. +.sp + PCRE2_INFO_HEAPLIMIT +.sp +If the pattern set a heap memory limit by including an item of the form +(*LIMIT_HEAP=nnnn) at the start, the value is returned. The third argument +should point to a uint32_t integer. If no such value has been set, the call to +\fBpcre2_pattern_info()\fP returns the error PCRE2_ERROR_UNSET. Note that this +limit will only be used during matching if it is less than the limit set or +defaulted by the caller of the match function. +.sp + PCRE2_INFO_JCHANGED +.sp +Return 1 if the (?J) or (?-J) option setting is used in the pattern, otherwise +0. The third argument should point to an \fBuint32_t\fP variable. (?J) and +(?-J) set and unset the local PCRE2_DUPNAMES option, respectively. +.sp + PCRE2_INFO_JITSIZE +.sp +If the compiled pattern was successfully processed by +\fBpcre2_jit_compile()\fP, return the size of the JIT compiled code, otherwise +return zero. The third argument should point to a \fBsize_t\fP variable. +.sp + PCRE2_INFO_LASTCODETYPE +.sp +Returns 1 if there is a rightmost literal code unit that must exist in any +matched string, other than at its start. The third argument should point to an +\fBuint32_t\fP variable. If there is no such value, 0 is returned. When 1 is +returned, the code unit value itself can be retrieved using +PCRE2_INFO_LASTCODEUNIT. For anchored patterns, a last literal value is +recorded only if it follows something of variable length. For example, for the +pattern /^a\ed+z\ed+/ the returned value is 1 (with "z" returned from +PCRE2_INFO_LASTCODEUNIT), but for /^a\edz\ed/ the returned value is 0. +.sp + PCRE2_INFO_LASTCODEUNIT +.sp +Return the value of the rightmost literal code unit that must exist in any +matched string, other than at its start, for a pattern where +PCRE2_INFO_LASTCODETYPE returns 1. Otherwise, return 0. The third argument +should point to an \fBuint32_t\fP variable. +.sp + PCRE2_INFO_MATCHEMPTY +.sp +Return 1 if the pattern might match an empty string, otherwise 0. The third +argument should point to an \fBuint32_t\fP variable. When a pattern contains +recursive subroutine calls it is not always possible to determine whether or +not it can match an empty string. PCRE2 takes a cautious approach and returns 1 +in such cases. +.sp + PCRE2_INFO_MATCHLIMIT +.sp +If the pattern set a match limit by including an item of the form +(*LIMIT_MATCH=nnnn) at the start, the value is returned. The third argument +should point to a uint32_t integer. If no such value has been set, the call to +\fBpcre2_pattern_info()\fP returns the error PCRE2_ERROR_UNSET. Note that this +limit will only be used during matching if it is less than the limit set or +defaulted by the caller of the match function. +.sp + PCRE2_INFO_MAXLOOKBEHIND +.sp +Return the number of characters (not code units) in the longest lookbehind +assertion in the pattern. The third argument should point to a uint32_t +integer. This information is useful when doing multi-segment matching using the +partial matching facilities. Note that the simple assertions \eb and \eB +require a one-character lookbehind. \eA also registers a one-character +lookbehind, though it does not actually inspect the previous character. This is +to ensure that at least one character from the old segment is retained when a +new segment is processed. Otherwise, if there are no lookbehinds in the +pattern, \eA might match incorrectly at the start of a second or subsequent +segment. +.sp + PCRE2_INFO_MINLENGTH +.sp +If a minimum length for matching subject strings was computed, its value is +returned. Otherwise the returned value is 0. The value is a number of +characters, which in UTF mode may be different from the number of code units. +The third argument should point to an \fBuint32_t\fP variable. The value is a +lower bound to the length of any matching string. There may not be any strings +of that length that do actually match, but every string that does match is at +least that long. +.sp + PCRE2_INFO_NAMECOUNT + PCRE2_INFO_NAMEENTRYSIZE + PCRE2_INFO_NAMETABLE +.sp +PCRE2 supports the use of named as well as numbered capturing parentheses. The +names are just an additional way of identifying the parentheses, which still +acquire numbers. Several convenience functions such as +\fBpcre2_substring_get_byname()\fP are provided for extracting captured +substrings by name. It is also possible to extract the data directly, by first +converting the name to a number in order to access the correct pointers in the +output vector (described with \fBpcre2_match()\fP below). To do the conversion, +you need to use the name-to-number map, which is described by these three +values. +.P +The map consists of a number of fixed-size entries. PCRE2_INFO_NAMECOUNT gives +the number of entries, and PCRE2_INFO_NAMEENTRYSIZE gives the size of each +entry in code units; both of these return a \fBuint32_t\fP value. The entry +size depends on the length of the longest name. +.P +PCRE2_INFO_NAMETABLE returns a pointer to the first entry of the table. This is +a PCRE2_SPTR pointer to a block of code units. In the 8-bit library, the first +two bytes of each entry are the number of the capturing parenthesis, most +significant byte first. In the 16-bit library, the pointer points to 16-bit +code units, the first of which contains the parenthesis number. In the 32-bit +library, the pointer points to 32-bit code units, the first of which contains +the parenthesis number. The rest of the entry is the corresponding name, zero +terminated. +.P +The names are in alphabetical order. If (?| is used to create multiple groups +with the same number, as described in the +.\" HTML +.\" +section on duplicate subpattern numbers +.\" +in the +.\" HREF +\fBpcre2pattern\fP +.\" +page, the groups may be given the same name, but there is only one entry in the +table. Different names for groups of the same number are not permitted. +.P +Duplicate names for subpatterns with different numbers are permitted, but only +if PCRE2_DUPNAMES is set. They appear in the table in the order in which they +were found in the pattern. In the absence of (?| this is the order of +increasing number; when (?| is used this is not necessarily the case because +later subpatterns may have lower numbers. +.P +As a simple example of the name/number table, consider the following pattern +after compilation by the 8-bit library (assume PCRE2_EXTENDED is set, so white +space - including newlines - is ignored): +.sp +.\" JOIN + (? (?(\ed\ed)?\ed\ed) - + (?\ed\ed) - (?\ed\ed) ) +.sp +There are four named subpatterns, so the table has four entries, and each entry +in the table is eight bytes long. The table is as follows, with non-printing +bytes shows in hexadecimal, and undefined bytes shown as ??: +.sp + 00 01 d a t e 00 ?? + 00 05 d a y 00 ?? ?? + 00 04 m o n t h 00 + 00 02 y e a r 00 ?? +.sp +When writing code to extract data from named subpatterns using the +name-to-number map, remember that the length of the entries is likely to be +different for each compiled pattern. +.sp + PCRE2_INFO_NEWLINE +.sp +The output is one of the following \fBuint32_t\fP values: +.sp + PCRE2_NEWLINE_CR Carriage return (CR) + PCRE2_NEWLINE_LF Linefeed (LF) + PCRE2_NEWLINE_CRLF Carriage return, linefeed (CRLF) + PCRE2_NEWLINE_ANY Any Unicode line ending + PCRE2_NEWLINE_ANYCRLF Any of CR, LF, or CRLF + PCRE2_NEWLINE_NUL The NUL character (binary zero) +.sp +This identifies the character sequence that will be recognized as meaning +"newline" while matching. +.sp + PCRE2_INFO_SIZE +.sp +Return the size of the compiled pattern in bytes (for all three libraries). The +third argument should point to a \fBsize_t\fP variable. This value includes the +size of the general data block that precedes the code units of the compiled +pattern itself. The value that is used when \fBpcre2_compile()\fP is getting +memory in which to place the compiled pattern may be slightly larger than the +value returned by this option, because there are cases where the code that +calculates the size has to over-estimate. Processing a pattern with the JIT +compiler does not alter the value returned by this option. +. +. +.\" HTML +.SH "INFORMATION ABOUT A PATTERN'S CALLOUTS" +.rs +.sp +.nf +.B int pcre2_callout_enumerate(const pcre2_code *\fIcode\fP, +.B " int (*\fIcallback\fP)(pcre2_callout_enumerate_block *, void *)," +.B " void *\fIuser_data\fP);" +.fi +.sp +A script language that supports the use of string arguments in callouts might +like to scan all the callouts in a pattern before running the match. This can +be done by calling \fBpcre2_callout_enumerate()\fP. The first argument is a +pointer to a compiled pattern, the second points to a callback function, and +the third is arbitrary user data. The callback function is called for every +callout in the pattern in the order in which they appear. Its first argument is +a pointer to a callout enumeration block, and its second argument is the +\fIuser_data\fP value that was passed to \fBpcre2_callout_enumerate()\fP. The +contents of the callout enumeration block are described in the +.\" HREF +\fBpcre2callout\fP +.\" +documentation, which also gives further details about callouts. +. +. +.SH "SERIALIZATION AND PRECOMPILING" +.rs +.sp +It is possible to save compiled patterns on disc or elsewhere, and reload them +later, subject to a number of restrictions. The host on which the patterns are +reloaded must be running the same version of PCRE2, with the same code unit +width, and must also have the same endianness, pointer width, and PCRE2_SIZE +type. Before compiled patterns can be saved, they must be converted to a +"serialized" form, which in the case of PCRE2 is really just a bytecode dump. +The functions whose names begin with \fBpcre2_serialize_\fP are used for +converting to and from the serialized form. They are described in the +.\" HREF +\fBpcre2serialize\fP +.\" +documentation. Note that PCRE2 serialization does not convert compiled patterns +to an abstract format like Java or .NET serialization. +. +. +.\" HTML +.SH "THE MATCH DATA BLOCK" +.rs +.sp +.nf +.B pcre2_match_data *pcre2_match_data_create(uint32_t \fIovecsize\fP, +.B " pcre2_general_context *\fIgcontext\fP);" +.sp +.B pcre2_match_data *pcre2_match_data_create_from_pattern( +.B " const pcre2_code *\fIcode\fP, pcre2_general_context *\fIgcontext\fP);" +.sp +.B void pcre2_match_data_free(pcre2_match_data *\fImatch_data\fP); +.fi +.P +Information about a successful or unsuccessful match is placed in a match +data block, which is an opaque structure that is accessed by function calls. In +particular, the match data block contains a vector of offsets into the subject +string that define the matched part of the subject and any substrings that were +captured. This is known as the \fIovector\fP. +.P +Before calling \fBpcre2_match()\fP, \fBpcre2_dfa_match()\fP, or +\fBpcre2_jit_match()\fP you must create a match data block by calling one of +the creation functions above. For \fBpcre2_match_data_create()\fP, the first +argument is the number of pairs of offsets in the \fIovector\fP. One pair of +offsets is required to identify the string that matched the whole pattern, with +an additional pair for each captured substring. For example, a value of 4 +creates enough space to record the matched portion of the subject plus three +captured substrings. A minimum of at least 1 pair is imposed by +\fBpcre2_match_data_create()\fP, so it is always possible to return the overall +matched string. +.P +The second argument of \fBpcre2_match_data_create()\fP is a pointer to a +general context, which can specify custom memory management for obtaining the +memory for the match data block. If you are not using custom memory management, +pass NULL, which causes \fBmalloc()\fP to be used. +.P +For \fBpcre2_match_data_create_from_pattern()\fP, the first argument is a +pointer to a compiled pattern. The ovector is created to be exactly the right +size to hold all the substrings a pattern might capture. The second argument is +again a pointer to a general context, but in this case if NULL is passed, the +memory is obtained using the same allocator that was used for the compiled +pattern (custom or default). +.P +A match data block can be used many times, with the same or different compiled +patterns. You can extract information from a match data block after a match +operation has finished, using functions that are described in the sections on +.\" HTML +.\" +matched strings +.\" +and +.\" HTML +.\" +other match data +.\" +below. +.P +When a call of \fBpcre2_match()\fP fails, valid data is available in the match +block only when the error is PCRE2_ERROR_NOMATCH, PCRE2_ERROR_PARTIAL, or one +of the error codes for an invalid UTF string. Exactly what is available depends +on the error, and is detailed below. +.P +When one of the matching functions is called, pointers to the compiled pattern +and the subject string are set in the match data block so that they can be +referenced by the extraction functions. After running a match, you must not +free a compiled pattern or a subject string until after all operations on the +match data block (for that match) have taken place. +.P +When a match data block itself is no longer needed, it should be freed by +calling \fBpcre2_match_data_free()\fP. If this function is called with a NULL +argument, it returns immediately, without doing anything. +. +. +.SH "MATCHING A PATTERN: THE TRADITIONAL FUNCTION" +.rs +.sp +.nf +.B int pcre2_match(const pcre2_code *\fIcode\fP, PCRE2_SPTR \fIsubject\fP, +.B " PCRE2_SIZE \fIlength\fP, PCRE2_SIZE \fIstartoffset\fP," +.B " uint32_t \fIoptions\fP, pcre2_match_data *\fImatch_data\fP," +.B " pcre2_match_context *\fImcontext\fP);" +.fi +.P +The function \fBpcre2_match()\fP is called to match a subject string against a +compiled pattern, which is passed in the \fIcode\fP argument. You can call +\fBpcre2_match()\fP with the same \fIcode\fP argument as many times as you +like, in order to find multiple matches in the subject string or to match +different subject strings with the same pattern. +.P +This function is the main matching facility of the library, and it operates in +a Perl-like manner. For specialist use there is also an alternative matching +function, which is described +.\" HTML +.\" +below +.\" +in the section about the \fBpcre2_dfa_match()\fP function. +.P +Here is an example of a simple call to \fBpcre2_match()\fP: +.sp + pcre2_match_data *md = pcre2_match_data_create(4, NULL); + int rc = pcre2_match( + re, /* result of pcre2_compile() */ + "some string", /* the subject string */ + 11, /* the length of the subject string */ + 0, /* start at offset 0 in the subject */ + 0, /* default options */ + md, /* the match data block */ + NULL); /* a match context; NULL means use defaults */ +.sp +If the subject string is zero-terminated, the length can be given as +PCRE2_ZERO_TERMINATED. A match context must be provided if certain less common +matching parameters are to be changed. For details, see the section on +.\" HTML +.\" +the match context +.\" +above. +. +. +.SS "The string to be matched by \fBpcre2_match()\fP" +.rs +.sp +The subject string is passed to \fBpcre2_match()\fP as a pointer in +\fIsubject\fP, a length in \fIlength\fP, and a starting offset in +\fIstartoffset\fP. The length and offset are in code units, not characters. +That is, they are in bytes for the 8-bit library, 16-bit code units for the +16-bit library, and 32-bit code units for the 32-bit library, whether or not +UTF processing is enabled. +.P +If \fIstartoffset\fP is greater than the length of the subject, +\fBpcre2_match()\fP returns PCRE2_ERROR_BADOFFSET. When the starting offset is +zero, the search for a match starts at the beginning of the subject, and this +is by far the most common case. In UTF-8 or UTF-16 mode, the starting offset +must point to the start of a character, or to the end of the subject (in UTF-32 +mode, one code unit equals one character, so all offsets are valid). Like the +pattern string, the subject may contain binary zeros. +.P +A non-zero starting offset is useful when searching for another match in the +same subject by calling \fBpcre2_match()\fP again after a previous success. +Setting \fIstartoffset\fP differs from passing over a shortened string and +setting PCRE2_NOTBOL in the case of a pattern that begins with any kind of +lookbehind. For example, consider the pattern +.sp + \eBiss\eB +.sp +which finds occurrences of "iss" in the middle of words. (\eB matches only if +the current position in the subject is not a word boundary.) When applied to +the string "Mississipi" the first call to \fBpcre2_match()\fP finds the first +occurrence. If \fBpcre2_match()\fP is called again with just the remainder of +the subject, namely "issipi", it does not match, because \eB is always false at +the start of the subject, which is deemed to be a word boundary. However, if +\fBpcre2_match()\fP is passed the entire string again, but with +\fIstartoffset\fP set to 4, it finds the second occurrence of "iss" because it +is able to look behind the starting point to discover that it is preceded by a +letter. +.P +Finding all the matches in a subject is tricky when the pattern can match an +empty string. It is possible to emulate Perl's /g behaviour by first trying the +match again at the same offset, with the PCRE2_NOTEMPTY_ATSTART and +PCRE2_ANCHORED options, and then if that fails, advancing the starting offset +and trying an ordinary match again. There is some code that demonstrates how to +do this in the +.\" HREF +\fBpcre2demo\fP +.\" +sample program. In the most general case, you have to check to see if the +newline convention recognizes CRLF as a newline, and if so, and the current +character is CR followed by LF, advance the starting offset by two characters +instead of one. +.P +If a non-zero starting offset is passed when the pattern is anchored, a single +attempt to match at the given offset is made. This can only succeed if the +pattern does not require the match to be at the start of the subject. In other +words, the anchoring must be the result of setting the PCRE2_ANCHORED option or +the use of .* with PCRE2_DOTALL, not by starting the pattern with ^ or \eA. +. +. +.\" HTML +.SS "Option bits for \fBpcre2_match()\fP" +.rs +.sp +The unused bits of the \fIoptions\fP argument for \fBpcre2_match()\fP must be +zero. The only bits that may be set are PCRE2_ANCHORED, PCRE2_ENDANCHORED, +PCRE2_NOTBOL, PCRE2_NOTEOL, PCRE2_NOTEMPTY, PCRE2_NOTEMPTY_ATSTART, +PCRE2_NO_JIT, PCRE2_NO_UTF_CHECK, PCRE2_PARTIAL_HARD, and PCRE2_PARTIAL_SOFT. +Their action is described below. +.P +Setting PCRE2_ANCHORED or PCRE2_ENDANCHORED at match time is not supported by +the just-in-time (JIT) compiler. If it is set, JIT matching is disabled and the +interpretive code in \fBpcre2_match()\fP is run. Apart from PCRE2_NO_JIT +(obviously), the remaining options are supported for JIT matching. +.sp + PCRE2_ANCHORED +.sp +The PCRE2_ANCHORED option limits \fBpcre2_match()\fP to matching at the first +matching position. If a pattern was compiled with PCRE2_ANCHORED, or turned out +to be anchored by virtue of its contents, it cannot be made unachored at +matching time. Note that setting the option at match time disables JIT +matching. +.sp + PCRE2_ENDANCHORED +.sp +If the PCRE2_ENDANCHORED option is set, any string that \fBpcre2_match()\fP +matches must be right at the end of the subject string. Note that setting the +option at match time disables JIT matching. +.sp + PCRE2_NOTBOL +.sp +This option specifies that first character of the subject string is not the +beginning of a line, so the circumflex metacharacter should not match before +it. Setting this without having set PCRE2_MULTILINE at compile time causes +circumflex never to match. This option affects only the behaviour of the +circumflex metacharacter. It does not affect \eA. +.sp + PCRE2_NOTEOL +.sp +This option specifies that the end of the subject string is not the end of a +line, so the dollar metacharacter should not match it nor (except in multiline +mode) a newline immediately before it. Setting this without having set +PCRE2_MULTILINE at compile time causes dollar never to match. This option +affects only the behaviour of the dollar metacharacter. It does not affect \eZ +or \ez. +.sp + PCRE2_NOTEMPTY +.sp +An empty string is not considered to be a valid match if this option is set. If +there are alternatives in the pattern, they are tried. If all the alternatives +match the empty string, the entire match fails. For example, if the pattern +.sp + a?b? +.sp +is applied to a string not beginning with "a" or "b", it matches an empty +string at the start of the subject. With PCRE2_NOTEMPTY set, this match is not +valid, so \fBpcre2_match()\fP searches further into the string for occurrences +of "a" or "b". +.sp + PCRE2_NOTEMPTY_ATSTART +.sp +This is like PCRE2_NOTEMPTY, except that it locks out an empty string match +only at the first matching position, that is, at the start of the subject plus +the starting offset. An empty string match later in the subject is permitted. +If the pattern is anchored, such a match can occur only if the pattern contains +\eK. +.sp + PCRE2_NO_JIT +.sp +By default, if a pattern has been successfully processed by +\fBpcre2_jit_compile()\fP, JIT is automatically used when \fBpcre2_match()\fP +is called with options that JIT supports. Setting PCRE2_NO_JIT disables the use +of JIT; it forces matching to be done by the interpreter. +.sp + PCRE2_NO_UTF_CHECK +.sp +When PCRE2_UTF is set at compile time, the validity of the subject as a UTF +string is checked by default when \fBpcre2_match()\fP is subsequently called. +If a non-zero starting offset is given, the check is applied only to that part +of the subject that could be inspected during matching, and there is a check +that the starting offset points to the first code unit of a character or to the +end of the subject. If there are no lookbehind assertions in the pattern, the +check starts at the starting offset. Otherwise, it starts at the length of the +longest lookbehind before the starting offset, or at the start of the subject +if there are not that many characters before the starting offset. Note that the +sequences \eb and \eB are one-character lookbehinds. +.P +The check is carried out before any other processing takes place, and a +negative error code is returned if the check fails. There are several UTF error +codes for each code unit width, corresponding to different problems with the +code unit sequence. There are discussions about the validity of +.\" HTML +.\" +UTF-8 strings, +.\" +.\" HTML +.\" +UTF-16 strings, +.\" +and +.\" HTML +.\" +UTF-32 strings +.\" +in the +.\" HREF +\fBpcre2unicode\fP +.\" +page. +.P +If you know that your subject is valid, and you want to skip these checks for +performance reasons, you can set the PCRE2_NO_UTF_CHECK option when calling +\fBpcre2_match()\fP. You might want to do this for the second and subsequent +calls to \fBpcre2_match()\fP if you are making repeated calls to find other +matches in the same subject string. +.P +\fBWarning:\fP When PCRE2_NO_UTF_CHECK is set, the effect of passing an invalid +string as a subject, or an invalid value of \fIstartoffset\fP, is undefined. +Your program may crash or loop indefinitely. +.sp + PCRE2_PARTIAL_HARD + PCRE2_PARTIAL_SOFT +.sp +These options turn on the partial matching feature. A partial match occurs if +the end of the subject string is reached successfully, but there are not enough +subject characters to complete the match. If this happens when +PCRE2_PARTIAL_SOFT (but not PCRE2_PARTIAL_HARD) is set, matching continues by +testing any remaining alternatives. Only if no complete match can be found is +PCRE2_ERROR_PARTIAL returned instead of PCRE2_ERROR_NOMATCH. In other words, +PCRE2_PARTIAL_SOFT specifies that the caller is prepared to handle a partial +match, but only if no complete match can be found. +.P +If PCRE2_PARTIAL_HARD is set, it overrides PCRE2_PARTIAL_SOFT. In this case, if +a partial match is found, \fBpcre2_match()\fP immediately returns +PCRE2_ERROR_PARTIAL, without considering any other alternatives. In other +words, when PCRE2_PARTIAL_HARD is set, a partial match is considered to be more +important that an alternative complete match. +.P +There is a more detailed discussion of partial and multi-segment matching, with +examples, in the +.\" HREF +\fBpcre2partial\fP +.\" +documentation. +. +. +. +.SH "NEWLINE HANDLING WHEN MATCHING" +.rs +.sp +When PCRE2 is built, a default newline convention is set; this is usually the +standard convention for the operating system. The default can be overridden in +a +.\" HTML +.\" +compile context +.\" +by calling \fBpcre2_set_newline()\fP. It can also be overridden by starting a +pattern string with, for example, (*CRLF), as described in the +.\" HTML +.\" +section on newline conventions +.\" +in the +.\" HREF +\fBpcre2pattern\fP +.\" +page. During matching, the newline choice affects the behaviour of the dot, +circumflex, and dollar metacharacters. It may also alter the way the match +starting position is advanced after a match failure for an unanchored pattern. +.P +When PCRE2_NEWLINE_CRLF, PCRE2_NEWLINE_ANYCRLF, or PCRE2_NEWLINE_ANY is set as +the newline convention, and a match attempt for an unanchored pattern fails +when the current starting position is at a CRLF sequence, and the pattern +contains no explicit matches for CR or LF characters, the match position is +advanced by two characters instead of one, in other words, to after the CRLF. +.P +The above rule is a compromise that makes the most common cases work as +expected. For example, if the pattern is .+A (and the PCRE2_DOTALL option is +not set), it does not match the string "\er\enA" because, after failing at the +start, it skips both the CR and the LF before retrying. However, the pattern +[\er\en]A does match that string, because it contains an explicit CR or LF +reference, and so advances only by one character after the first failure. +.P +An explicit match for CR of LF is either a literal appearance of one of those +characters in the pattern, or one of the \er or \en or equivalent octal or +hexadecimal escape sequences. Implicit matches such as [^X] do not count, nor +does \es, even though it includes CR and LF in the characters that it matches. +.P +Notwithstanding the above, anomalous effects may still occur when CRLF is a +valid newline sequence and explicit \er or \en escapes appear in the pattern. +. +. +.\" HTML +.SH "HOW PCRE2_MATCH() RETURNS A STRING AND CAPTURED SUBSTRINGS" +.rs +.sp +.nf +.B uint32_t pcre2_get_ovector_count(pcre2_match_data *\fImatch_data\fP); +.sp +.B PCRE2_SIZE *pcre2_get_ovector_pointer(pcre2_match_data *\fImatch_data\fP); +.fi +.P +In general, a pattern matches a certain portion of the subject, and in +addition, further substrings from the subject may be picked out by +parenthesized parts of the pattern. Following the usage in Jeffrey Friedl's +book, this is called "capturing" in what follows, and the phrase "capturing +subpattern" or "capturing group" is used for a fragment of a pattern that picks +out a substring. PCRE2 supports several other kinds of parenthesized subpattern +that do not cause substrings to be captured. The \fBpcre2_pattern_info()\fP +function can be used to find out how many capturing subpatterns there are in a +compiled pattern. +.P +You can use auxiliary functions for accessing captured substrings +.\" HTML +.\" +by number +.\" +or +.\" HTML +.\" +by name, +.\" +as described in sections below. +.P +Alternatively, you can make direct use of the vector of PCRE2_SIZE values, +called the \fBovector\fP, which contains the offsets of captured strings. It is +part of the +.\" HTML +.\" +match data block. +.\" +The function \fBpcre2_get_ovector_pointer()\fP returns the address of the +ovector, and \fBpcre2_get_ovector_count()\fP returns the number of pairs of +values it contains. +.P +Within the ovector, the first in each pair of values is set to the offset of +the first code unit of a substring, and the second is set to the offset of the +first code unit after the end of a substring. These values are always code unit +offsets, not character offsets. That is, they are byte offsets in the 8-bit +library, 16-bit offsets in the 16-bit library, and 32-bit offsets in the 32-bit +library. +.P +After a partial match (error return PCRE2_ERROR_PARTIAL), only the first pair +of offsets (that is, \fIovector[0]\fP and \fIovector[1]\fP) are set. They +identify the part of the subject that was partially matched. See the +.\" HREF +\fBpcre2partial\fP +.\" +documentation for details of partial matching. +.P +After a fully successful match, the first pair of offsets identifies the +portion of the subject string that was matched by the entire pattern. The next +pair is used for the first captured substring, and so on. The value returned by +\fBpcre2_match()\fP is one more than the highest numbered pair that has been +set. For example, if two substrings have been captured, the returned value is +3. If there are no captured substrings, the return value from a successful +match is 1, indicating that just the first pair of offsets has been set. +.P +If a pattern uses the \eK escape sequence within a positive assertion, the +reported start of a successful match can be greater than the end of the match. +For example, if the pattern (?=ab\eK) is matched against "ab", the start and +end offset values for the match are 2 and 0. +.P +If a capturing subpattern group is matched repeatedly within a single match +operation, it is the last portion of the subject that it matched that is +returned. +.P +If the ovector is too small to hold all the captured substring offsets, as much +as possible is filled in, and the function returns a value of zero. If captured +substrings are not of interest, \fBpcre2_match()\fP may be called with a match +data block whose ovector is of minimum length (that is, one pair). +.P +It is possible for capturing subpattern number \fIn+1\fP to match some part of +the subject when subpattern \fIn\fP has not been used at all. For example, if +the string "abc" is matched against the pattern (a|(z))(bc) the return from the +function is 4, and subpatterns 1 and 3 are matched, but 2 is not. When this +happens, both values in the offset pairs corresponding to unused subpatterns +are set to PCRE2_UNSET. +.P +Offset values that correspond to unused subpatterns at the end of the +expression are also set to PCRE2_UNSET. For example, if the string "abc" is +matched against the pattern (abc)(x(yz)?)? subpatterns 2 and 3 are not matched. +The return from the function is 2, because the highest used capturing +subpattern number is 1. The offsets for for the second and third capturing +subpatterns (assuming the vector is large enough, of course) are set to +PCRE2_UNSET. +.P +Elements in the ovector that do not correspond to capturing parentheses in the +pattern are never changed. That is, if a pattern contains \fIn\fP capturing +parentheses, no more than \fIovector[0]\fP to \fIovector[2n+1]\fP are set by +\fBpcre2_match()\fP. The other elements retain whatever values they previously +had. After a failed match attempt, the contents of the ovector are unchanged. +. +. +.\" HTML +.SH "OTHER INFORMATION ABOUT A MATCH" +.rs +.sp +.nf +.B PCRE2_SPTR pcre2_get_mark(pcre2_match_data *\fImatch_data\fP); +.sp +.B PCRE2_SIZE pcre2_get_startchar(pcre2_match_data *\fImatch_data\fP); +.fi +.P +As well as the offsets in the ovector, other information about a match is +retained in the match data block and can be retrieved by the above functions in +appropriate circumstances. If they are called at other times, the result is +undefined. +.P +After a successful match, a partial match (PCRE2_ERROR_PARTIAL), or a failure +to match (PCRE2_ERROR_NOMATCH), a (*MARK), (*PRUNE), or (*THEN) name may be +available. The function \fBpcre2_get_mark()\fP can be called to access this +name. The same function applies to all three verbs. It returns a pointer to the +zero-terminated name, which is within the compiled pattern. If no name is +available, NULL is returned. The length of the name (excluding the terminating +zero) is stored in the code unit that precedes the name. You should use this +length instead of relying on the terminating zero if the name might contain a +binary zero. +.P +After a successful match, the name that is returned is the last (*MARK), +(*PRUNE), or (*THEN) name encountered on the matching path through the pattern. +Instances of (*PRUNE) and (*THEN) without names are ignored. Thus, for example, +if the matching path contains (*MARK:A)(*PRUNE), the name "A" is returned. +After a "no match" or a partial match, the last encountered name is returned. +For example, consider this pattern: +.sp + ^(*MARK:A)((*MARK:B)a|b)c +.sp +When it matches "bc", the returned name is A. The B mark is "seen" in the first +branch of the group, but it is not on the matching path. On the other hand, +when this pattern fails to match "bx", the returned name is B. +.P +\fBWarning:\fP By default, certain start-of-match optimizations are used to +give a fast "no match" result in some situations. For example, if the anchoring +is removed from the pattern above, there is an initial check for the presence +of "c" in the subject before running the matching engine. This check fails for +"bx", causing a match failure without seeing any marks. You can disable the +start-of-match optimizations by setting the PCRE2_NO_START_OPTIMIZE option for +\fBpcre2_compile()\fP or starting the pattern with (*NO_START_OPT). +.P +After a successful match, a partial match, or one of the invalid UTF errors +(for example, PCRE2_ERROR_UTF8_ERR5), \fBpcre2_get_startchar()\fP can be +called. After a successful or partial match it returns the code unit offset of +the character at which the match started. For a non-partial match, this can be +different to the value of \fIovector[0]\fP if the pattern contains the \eK +escape sequence. After a partial match, however, this value is always the same +as \fIovector[0]\fP because \eK does not affect the result of a partial match. +.P +After a UTF check failure, \fBpcre2_get_startchar()\fP can be used to obtain +the code unit offset of the invalid UTF character. Details are given in the +.\" HREF +\fBpcre2unicode\fP +.\" +page. +. +. +.\" HTML +.SH "ERROR RETURNS FROM \fBpcre2_match()\fP" +.rs +.sp +If \fBpcre2_match()\fP fails, it returns a negative number. This can be +converted to a text string by calling the \fBpcre2_get_error_message()\fP +function (see "Obtaining a textual error message" +.\" HTML +.\" +below). +.\" +Negative error codes are also returned by other functions, and are documented +with them. The codes are given names in the header file. If UTF checking is in +force and an invalid UTF subject string is detected, one of a number of +UTF-specific negative error codes is returned. Details are given in the +.\" HREF +\fBpcre2unicode\fP +.\" +page. The following are the other errors that may be returned by +\fBpcre2_match()\fP: +.sp + PCRE2_ERROR_NOMATCH +.sp +The subject string did not match the pattern. +.sp + PCRE2_ERROR_PARTIAL +.sp +The subject string did not match, but it did match partially. See the +.\" HREF +\fBpcre2partial\fP +.\" +documentation for details of partial matching. +.sp + PCRE2_ERROR_BADMAGIC +.sp +PCRE2 stores a 4-byte "magic number" at the start of the compiled code, to +catch the case when it is passed a junk pointer. This is the error that is +returned when the magic number is not present. +.sp + PCRE2_ERROR_BADMODE +.sp +This error is given when a compiled pattern is passed to a function in a +library of a different code unit width, for example, a pattern compiled by +the 8-bit library is passed to a 16-bit or 32-bit library function. +.sp + PCRE2_ERROR_BADOFFSET +.sp +The value of \fIstartoffset\fP was greater than the length of the subject. +.sp + PCRE2_ERROR_BADOPTION +.sp +An unrecognized bit was set in the \fIoptions\fP argument. +.sp + PCRE2_ERROR_BADUTFOFFSET +.sp +The UTF code unit sequence that was passed as a subject was checked and found +to be valid (the PCRE2_NO_UTF_CHECK option was not set), but the value of +\fIstartoffset\fP did not point to the beginning of a UTF character or the end +of the subject. +.sp + PCRE2_ERROR_CALLOUT +.sp +This error is never generated by \fBpcre2_match()\fP itself. It is provided for +use by callout functions that want to cause \fBpcre2_match()\fP or +\fBpcre2_callout_enumerate()\fP to return a distinctive error code. See the +.\" HREF +\fBpcre2callout\fP +.\" +documentation for details. +.sp + PCRE2_ERROR_DEPTHLIMIT +.sp +The nested backtracking depth limit was reached. +.sp + PCRE2_ERROR_HEAPLIMIT +.sp +The heap limit was reached. +.sp + PCRE2_ERROR_INTERNAL +.sp +An unexpected internal error has occurred. This error could be caused by a bug +in PCRE2 or by overwriting of the compiled pattern. +.sp + PCRE2_ERROR_JIT_STACKLIMIT +.sp +This error is returned when a pattern that was successfully studied using JIT +is being matched, but the memory available for the just-in-time processing +stack is not large enough. See the +.\" HREF +\fBpcre2jit\fP +.\" +documentation for more details. +.sp + PCRE2_ERROR_MATCHLIMIT +.sp +The backtracking match limit was reached. +.sp + PCRE2_ERROR_NOMEMORY +.sp +If a pattern contains many nested backtracking points, heap memory is used to +remember them. This error is given when the memory allocation function (default +or custom) fails. Note that a different error, PCRE2_ERROR_HEAPLIMIT, is given +if the amount of memory needed exceeds the heap limit. +.sp + PCRE2_ERROR_NULL +.sp +Either the \fIcode\fP, \fIsubject\fP, or \fImatch_data\fP argument was passed +as NULL. +.sp + PCRE2_ERROR_RECURSELOOP +.sp +This error is returned when \fBpcre2_match()\fP detects a recursion loop within +the pattern. Specifically, it means that either the whole pattern or a +subpattern has been called recursively for the second time at the same position +in the subject string. Some simple patterns that might do this are detected and +faulted at compile time, but more complicated cases, in particular mutual +recursions between two different subpatterns, cannot be detected until matching +is attempted. +. +. +.\" HTML +.SH "OBTAINING A TEXTUAL ERROR MESSAGE" +.rs +.sp +.nf +.B int pcre2_get_error_message(int \fIerrorcode\fP, PCRE2_UCHAR *\fIbuffer\fP, +.B " PCRE2_SIZE \fIbufflen\fP);" +.fi +.P +A text message for an error code from any PCRE2 function (compile, match, or +auxiliary) can be obtained by calling \fBpcre2_get_error_message()\fP. The code +is passed as the first argument, with the remaining two arguments specifying a +code unit buffer and its length in code units, into which the text message is +placed. The message is returned in code units of the appropriate width for the +library that is being used. +.P +The returned message is terminated with a trailing zero, and the function +returns the number of code units used, excluding the trailing zero. If the +error number is unknown, the negative error code PCRE2_ERROR_BADDATA is +returned. If the buffer is too small, the message is truncated (but still with +a trailing zero), and the negative error code PCRE2_ERROR_NOMEMORY is returned. +None of the messages are very long; a buffer size of 120 code units is ample. +. +. +.\" HTML +.SH "EXTRACTING CAPTURED SUBSTRINGS BY NUMBER" +.rs +.sp +.nf +.B int pcre2_substring_length_bynumber(pcre2_match_data *\fImatch_data\fP, +.B " uint32_t \fInumber\fP, PCRE2_SIZE *\fIlength\fP);" +.sp +.B int pcre2_substring_copy_bynumber(pcre2_match_data *\fImatch_data\fP, +.B " uint32_t \fInumber\fP, PCRE2_UCHAR *\fIbuffer\fP," +.B " PCRE2_SIZE *\fIbufflen\fP);" +.sp +.B int pcre2_substring_get_bynumber(pcre2_match_data *\fImatch_data\fP, +.B " uint32_t \fInumber\fP, PCRE2_UCHAR **\fIbufferptr\fP," +.B " PCRE2_SIZE *\fIbufflen\fP);" +.sp +.B void pcre2_substring_free(PCRE2_UCHAR *\fIbuffer\fP); +.fi +.P +Captured substrings can be accessed directly by using the ovector as described +.\" HTML +.\" +above. +.\" +For convenience, auxiliary functions are provided for extracting captured +substrings as new, separate, zero-terminated strings. A substring that contains +a binary zero is correctly extracted and has a further zero added on the end, +but the result is not, of course, a C string. +.P +The functions in this section identify substrings by number. The number zero +refers to the entire matched substring, with higher numbers referring to +substrings captured by parenthesized groups. After a partial match, only +substring zero is available. An attempt to extract any other substring gives +the error PCRE2_ERROR_PARTIAL. The next section describes similar functions for +extracting captured substrings by name. +.P +If a pattern uses the \eK escape sequence within a positive assertion, the +reported start of a successful match can be greater than the end of the match. +For example, if the pattern (?=ab\eK) is matched against "ab", the start and +end offset values for the match are 2 and 0. In this situation, calling these +functions with a zero substring number extracts a zero-length empty string. +.P +You can find the length in code units of a captured substring without +extracting it by calling \fBpcre2_substring_length_bynumber()\fP. The first +argument is a pointer to the match data block, the second is the group number, +and the third is a pointer to a variable into which the length is placed. If +you just want to know whether or not the substring has been captured, you can +pass the third argument as NULL. +.P +The \fBpcre2_substring_copy_bynumber()\fP function copies a captured substring +into a supplied buffer, whereas \fBpcre2_substring_get_bynumber()\fP copies it +into new memory, obtained using the same memory allocation function that was +used for the match data block. The first two arguments of these functions are a +pointer to the match data block and a capturing group number. +.P +The final arguments of \fBpcre2_substring_copy_bynumber()\fP are a pointer to +the buffer and a pointer to a variable that contains its length in code units. +This is updated to contain the actual number of code units used for the +extracted substring, excluding the terminating zero. +.P +For \fBpcre2_substring_get_bynumber()\fP the third and fourth arguments point +to variables that are updated with a pointer to the new memory and the number +of code units that comprise the substring, again excluding the terminating +zero. When the substring is no longer needed, the memory should be freed by +calling \fBpcre2_substring_free()\fP. +.P +The return value from all these functions is zero for success, or a negative +error code. If the pattern match failed, the match failure code is returned. +If a substring number greater than zero is used after a partial match, +PCRE2_ERROR_PARTIAL is returned. Other possible error codes are: +.sp + PCRE2_ERROR_NOMEMORY +.sp +The buffer was too small for \fBpcre2_substring_copy_bynumber()\fP, or the +attempt to get memory failed for \fBpcre2_substring_get_bynumber()\fP. +.sp + PCRE2_ERROR_NOSUBSTRING +.sp +There is no substring with that number in the pattern, that is, the number is +greater than the number of capturing parentheses. +.sp + PCRE2_ERROR_UNAVAILABLE +.sp +The substring number, though not greater than the number of captures in the +pattern, is greater than the number of slots in the ovector, so the substring +could not be captured. +.sp + PCRE2_ERROR_UNSET +.sp +The substring did not participate in the match. For example, if the pattern is +(abc)|(def) and the subject is "def", and the ovector contains at least two +capturing slots, substring number 1 is unset. +. +. +.SH "EXTRACTING A LIST OF ALL CAPTURED SUBSTRINGS" +.rs +.sp +.nf +.B int pcre2_substring_list_get(pcre2_match_data *\fImatch_data\fP, +.B " PCRE2_UCHAR ***\fIlistptr\fP, PCRE2_SIZE **\fIlengthsptr\fP); +.sp +.B void pcre2_substring_list_free(PCRE2_SPTR *\fIlist\fP); +.fi +.P +The \fBpcre2_substring_list_get()\fP function extracts all available substrings +and builds a list of pointers to them. It also (optionally) builds a second +list that contains their lengths (in code units), excluding a terminating zero +that is added to each of them. All this is done in a single block of memory +that is obtained using the same memory allocation function that was used to get +the match data block. +.P +This function must be called only after a successful match. If called after a +partial match, the error code PCRE2_ERROR_PARTIAL is returned. +.P +The address of the memory block is returned via \fIlistptr\fP, which is also +the start of the list of string pointers. The end of the list is marked by a +NULL pointer. The address of the list of lengths is returned via +\fIlengthsptr\fP. If your strings do not contain binary zeros and you do not +therefore need the lengths, you may supply NULL as the \fBlengthsptr\fP +argument to disable the creation of a list of lengths. The yield of the +function is zero if all went well, or PCRE2_ERROR_NOMEMORY if the memory block +could not be obtained. When the list is no longer needed, it should be freed by +calling \fBpcre2_substring_list_free()\fP. +.P +If this function encounters a substring that is unset, which can happen when +capturing subpattern number \fIn+1\fP matches some part of the subject, but +subpattern \fIn\fP has not been used at all, it returns an empty string. This +can be distinguished from a genuine zero-length substring by inspecting the +appropriate offset in the ovector, which contain PCRE2_UNSET for unset +substrings, or by calling \fBpcre2_substring_length_bynumber()\fP. +. +. +.\" HTML +.SH "EXTRACTING CAPTURED SUBSTRINGS BY NAME" +.rs +.sp +.nf +.B int pcre2_substring_number_from_name(const pcre2_code *\fIcode\fP, +.B " PCRE2_SPTR \fIname\fP);" +.sp +.B int pcre2_substring_length_byname(pcre2_match_data *\fImatch_data\fP, +.B " PCRE2_SPTR \fIname\fP, PCRE2_SIZE *\fIlength\fP);" +.sp +.B int pcre2_substring_copy_byname(pcre2_match_data *\fImatch_data\fP, +.B " PCRE2_SPTR \fIname\fP, PCRE2_UCHAR *\fIbuffer\fP, PCRE2_SIZE *\fIbufflen\fP);" +.sp +.B int pcre2_substring_get_byname(pcre2_match_data *\fImatch_data\fP, +.B " PCRE2_SPTR \fIname\fP, PCRE2_UCHAR **\fIbufferptr\fP, PCRE2_SIZE *\fIbufflen\fP);" +.sp +.B void pcre2_substring_free(PCRE2_UCHAR *\fIbuffer\fP); +.fi +.P +To extract a substring by name, you first have to find associated number. +For example, for this pattern: +.sp + (a+)b(?\ed+)... +.sp +the number of the subpattern called "xxx" is 2. If the name is known to be +unique (PCRE2_DUPNAMES was not set), you can find the number from the name by +calling \fBpcre2_substring_number_from_name()\fP. The first argument is the +compiled pattern, and the second is the name. The yield of the function is the +subpattern number, PCRE2_ERROR_NOSUBSTRING if there is no subpattern of that +name, or PCRE2_ERROR_NOUNIQUESUBSTRING if there is more than one subpattern of +that name. Given the number, you can extract the substring directly from the +ovector, or use one of the "bynumber" functions described above. +.P +For convenience, there are also "byname" functions that correspond to the +"bynumber" functions, the only difference being that the second argument is a +name instead of a number. If PCRE2_DUPNAMES is set and there are duplicate +names, these functions scan all the groups with the given name, and return the +first named string that is set. +.P +If there are no groups with the given name, PCRE2_ERROR_NOSUBSTRING is +returned. If all groups with the name have numbers that are greater than the +number of slots in the ovector, PCRE2_ERROR_UNAVAILABLE is returned. If there +is at least one group with a slot in the ovector, but no group is found to be +set, PCRE2_ERROR_UNSET is returned. +.P +\fBWarning:\fP If the pattern uses the (?| feature to set up multiple +subpatterns with the same number, as described in the +.\" HTML +.\" +section on duplicate subpattern numbers +.\" +in the +.\" HREF +\fBpcre2pattern\fP +.\" +page, you cannot use names to distinguish the different subpatterns, because +names are not included in the compiled code. The matching process uses only +numbers. For this reason, the use of different names for subpatterns of the +same number causes an error at compile time. +. +. +.SH "CREATING A NEW STRING WITH SUBSTITUTIONS" +.rs +.sp +.nf +.B int pcre2_substitute(const pcre2_code *\fIcode\fP, PCRE2_SPTR \fIsubject\fP, +.B " PCRE2_SIZE \fIlength\fP, PCRE2_SIZE \fIstartoffset\fP," +.B " uint32_t \fIoptions\fP, pcre2_match_data *\fImatch_data\fP," +.B " pcre2_match_context *\fImcontext\fP, PCRE2_SPTR \fIreplacement\fP," +.B " PCRE2_SIZE \fIrlength\fP, PCRE2_UCHAR *\fIoutputbuffer\zfP," +.B " PCRE2_SIZE *\fIoutlengthptr\fP);" +.fi +.P +This function calls \fBpcre2_match()\fP and then makes a copy of the subject +string in \fIoutputbuffer\fP, replacing the part that was matched with the +\fIreplacement\fP string, whose length is supplied in \fBrlength\fP. This can +be given as PCRE2_ZERO_TERMINATED for a zero-terminated string. Matches in +which a \eK item in a lookahead in the pattern causes the match to end before +it starts are not supported, and give rise to an error return. For global +replacements, matches in which \eK in a lookbehind causes the match to start +earlier than the point that was reached in the previous iteration are also not +supported. +.P +The first seven arguments of \fBpcre2_substitute()\fP are the same as for +\fBpcre2_match()\fP, except that the partial matching options are not +permitted, and \fImatch_data\fP may be passed as NULL, in which case a match +data block is obtained and freed within this function, using memory management +functions from the match context, if provided, or else those that were used to +allocate memory for the compiled code. +.P +If an external \fImatch_data\fP block is provided, its contents afterwards +are those set by the final call to \fBpcre2_match()\fP, which will have +ended in a matching error. The contents of the ovector within the match data +block may or may not have been changed. +.P +The \fIoutlengthptr\fP argument must point to a variable that contains the +length, in code units, of the output buffer. If the function is successful, the +value is updated to contain the length of the new string, excluding the +trailing zero that is automatically added. +.P +If the function is not successful, the value set via \fIoutlengthptr\fP depends +on the type of error. For syntax errors in the replacement string, the value is +the offset in the replacement string where the error was detected. For other +errors, the value is PCRE2_UNSET by default. This includes the case of the +output buffer being too small, unless PCRE2_SUBSTITUTE_OVERFLOW_LENGTH is set +(see below), in which case the value is the minimum length needed, including +space for the trailing zero. Note that in order to compute the required length, +\fBpcre2_substitute()\fP has to simulate all the matching and copying, instead +of giving an error return as soon as the buffer overflows. Note also that the +length is in code units, not bytes. +.P +In the replacement string, which is interpreted as a UTF string in UTF mode, +and is checked for UTF validity unless the PCRE2_NO_UTF_CHECK option is set, a +dollar character is an escape character that can specify the insertion of +characters from capturing groups or (*MARK), (*PRUNE), or (*THEN) items in the +pattern. The following forms are always recognized: +.sp + $$ insert a dollar character + $ or ${} insert the contents of group + $*MARK or ${*MARK} insert a (*MARK), (*PRUNE), or (*THEN) name +.sp +Either a group number or a group name can be given for . Curly brackets are +required only if the following character would be interpreted as part of the +number or name. The number may be zero to include the entire matched string. +For example, if the pattern a(b)c is matched with "=abc=" and the replacement +string "+$1$0$1+", the result is "=+babcb+=". +.P +$*MARK inserts the name from the last encountered (*MARK), (*PRUNE), or (*THEN) +on the matching path that has a name. (*MARK) must always include a name, but +(*PRUNE) and (*THEN) need not. For example, in the case of (*MARK:A)(*PRUNE) +the name inserted is "A", but for (*MARK:A)(*PRUNE:B) the relevant name is "B". +This facility can be used to perform simple simultaneous substitutions, as this +\fBpcre2test\fP example shows: +.sp + /(*MARK:pear)apple|(*MARK:orange)lemon/g,replace=${*MARK} + apple lemon + 2: pear orange +.sp +As well as the usual options for \fBpcre2_match()\fP, a number of additional +options can be set in the \fIoptions\fP argument of \fBpcre2_substitute()\fP. +.P +PCRE2_SUBSTITUTE_GLOBAL causes the function to iterate over the subject string, +replacing every matching substring. If this option is not set, only the first +matching substring is replaced. The search for matches takes place in the +original subject string (that is, previous replacements do not affect it). +Iteration is implemented by advancing the \fIstartoffset\fP value for each +search, which is always passed the entire subject string. If an offset limit is +set in the match context, searching stops when that limit is reached. +.P +You can restrict the effect of a global substitution to a portion of the +subject string by setting either or both of \fIstartoffset\fP and an offset +limit. Here is a \fPpcre2test\fP example: +.sp + /B/g,replace=!,use_offset_limit + ABC ABC ABC ABC\e=offset=3,offset_limit=12 + 2: ABC A!C A!C ABC +.sp +When continuing with global substitutions after matching a substring with zero +length, an attempt to find a non-empty match at the same offset is performed. +If this is not successful, the offset is advanced by one character except when +CRLF is a valid newline sequence and the next two characters are CR, LF. In +this case, the offset is advanced by two characters. +.P +PCRE2_SUBSTITUTE_OVERFLOW_LENGTH changes what happens when the output buffer is +too small. The default action is to return PCRE2_ERROR_NOMEMORY immediately. If +this option is set, however, \fBpcre2_substitute()\fP continues to go through +the motions of matching and substituting (without, of course, writing anything) +in order to compute the size of buffer that is needed. This value is passed +back via the \fIoutlengthptr\fP variable, with the result of the function still +being PCRE2_ERROR_NOMEMORY. +.P +Passing a buffer size of zero is a permitted way of finding out how much memory +is needed for given substitution. However, this does mean that the entire +operation is carried out twice. Depending on the application, it may be more +efficient to allocate a large buffer and free the excess afterwards, instead of +using PCRE2_SUBSTITUTE_OVERFLOW_LENGTH. +.P +PCRE2_SUBSTITUTE_UNKNOWN_UNSET causes references to capturing groups that do +not appear in the pattern to be treated as unset groups. This option should be +used with care, because it means that a typo in a group name or number no +longer causes the PCRE2_ERROR_NOSUBSTRING error. +.P +PCRE2_SUBSTITUTE_UNSET_EMPTY causes unset capturing groups (including unknown +groups when PCRE2_SUBSTITUTE_UNKNOWN_UNSET is set) to be treated as empty +strings when inserted as described above. If this option is not set, an attempt +to insert an unset group causes the PCRE2_ERROR_UNSET error. This option does +not influence the extended substitution syntax described below. +.P +PCRE2_SUBSTITUTE_EXTENDED causes extra processing to be applied to the +replacement string. Without this option, only the dollar character is special, +and only the group insertion forms listed above are valid. When +PCRE2_SUBSTITUTE_EXTENDED is set, two things change: +.P +Firstly, backslash in a replacement string is interpreted as an escape +character. The usual forms such as \en or \ex{ddd} can be used to specify +particular character codes, and backslash followed by any non-alphanumeric +character quotes that character. Extended quoting can be coded using \eQ...\eE, +exactly as in pattern strings. +.P +There are also four escape sequences for forcing the case of inserted letters. +The insertion mechanism has three states: no case forcing, force upper case, +and force lower case. The escape sequences change the current state: \eU and +\eL change to upper or lower case forcing, respectively, and \eE (when not +terminating a \eQ quoted sequence) reverts to no case forcing. The sequences +\eu and \el force the next character (if it is a letter) to upper or lower +case, respectively, and then the state automatically reverts to no case +forcing. Case forcing applies to all inserted characters, including those from +captured groups and letters within \eQ...\eE quoted sequences. +.P +Note that case forcing sequences such as \eU...\eE do not nest. For example, +the result of processing "\eUaa\eLBB\eEcc\eE" is "AAbbcc"; the final \eE has no +effect. +.P +The second effect of setting PCRE2_SUBSTITUTE_EXTENDED is to add more +flexibility to group substitution. The syntax is similar to that used by Bash: +.sp + ${:-} + ${:+:} +.sp +As before, may be a group number or a name. The first form specifies a +default value. If group is set, its value is inserted; if not, is +expanded and the result inserted. The second form specifies strings that are +expanded and inserted when group is set or unset, respectively. The first +form is just a convenient shorthand for +.sp + ${:+${}:} +.sp +Backslash can be used to escape colons and closing curly brackets in the +replacement strings. A change of the case forcing state within a replacement +string remains in force afterwards, as shown in this \fBpcre2test\fP example: +.sp + /(some)?(body)/substitute_extended,replace=${1:+\eU:\eL}HeLLo + body + 1: hello + somebody + 1: HELLO +.sp +The PCRE2_SUBSTITUTE_UNSET_EMPTY option does not affect these extended +substitutions. However, PCRE2_SUBSTITUTE_UNKNOWN_UNSET does cause unknown +groups in the extended syntax forms to be treated as unset. +.P +If successful, \fBpcre2_substitute()\fP returns the number of replacements that +were made. This may be zero if no matches were found, and is never greater than +1 unless PCRE2_SUBSTITUTE_GLOBAL is set. +.P +In the event of an error, a negative error code is returned. Except for +PCRE2_ERROR_NOMATCH (which is never returned), errors from \fBpcre2_match()\fP +are passed straight back. +.P +PCRE2_ERROR_NOSUBSTRING is returned for a non-existent substring insertion, +unless PCRE2_SUBSTITUTE_UNKNOWN_UNSET is set. +.P +PCRE2_ERROR_UNSET is returned for an unset substring insertion (including an +unknown substring when PCRE2_SUBSTITUTE_UNKNOWN_UNSET is set) when the simple +(non-extended) syntax is used and PCRE2_SUBSTITUTE_UNSET_EMPTY is not set. +.P +PCRE2_ERROR_NOMEMORY is returned if the output buffer is not big enough. If the +PCRE2_SUBSTITUTE_OVERFLOW_LENGTH option is set, the size of buffer that is +needed is returned via \fIoutlengthptr\fP. Note that this does not happen by +default. +.P +PCRE2_ERROR_BADREPLACEMENT is used for miscellaneous syntax errors in the +replacement string, with more particular errors being PCRE2_ERROR_BADREPESCAPE +(invalid escape sequence), PCRE2_ERROR_REPMISSINGBRACE (closing curly bracket +not found), PCRE2_ERROR_BADSUBSTITUTION (syntax error in extended group +substitution), and PCRE2_ERROR_BADSUBSPATTERN (the pattern match ended before +it started or the match started earlier than the current position in the +subject, which can happen if \eK is used in an assertion). +.P +As for all PCRE2 errors, a text message that describes the error can be +obtained by calling the \fBpcre2_get_error_message()\fP function (see +"Obtaining a textual error message" +.\" HTML +.\" +above). +.\" +. +. +.SH "DUPLICATE SUBPATTERN NAMES" +.rs +.sp +.nf +.B int pcre2_substring_nametable_scan(const pcre2_code *\fIcode\fP, +.B " PCRE2_SPTR \fIname\fP, PCRE2_SPTR *\fIfirst\fP, PCRE2_SPTR *\fIlast\fP);" +.fi +.P +When a pattern is compiled with the PCRE2_DUPNAMES option, names for +subpatterns are not required to be unique. Duplicate names are always allowed +for subpatterns with the same number, created by using the (?| feature. Indeed, +if such subpatterns are named, they are required to use the same names. +.P +Normally, patterns with duplicate names are such that in any one match, only +one of the named subpatterns participates. An example is shown in the +.\" HREF +\fBpcre2pattern\fP +.\" +documentation. +.P +When duplicates are present, \fBpcre2_substring_copy_byname()\fP and +\fBpcre2_substring_get_byname()\fP return the first substring corresponding to +the given name that is set. Only if none are set is PCRE2_ERROR_UNSET is +returned. The \fBpcre2_substring_number_from_name()\fP function returns the +error PCRE2_ERROR_NOUNIQUESUBSTRING when there are duplicate names. +.P +If you want to get full details of all captured substrings for a given name, +you must use the \fBpcre2_substring_nametable_scan()\fP function. The first +argument is the compiled pattern, and the second is the name. If the third and +fourth arguments are NULL, the function returns a group number for a unique +name, or PCRE2_ERROR_NOUNIQUESUBSTRING otherwise. +.P +When the third and fourth arguments are not NULL, they must be pointers to +variables that are updated by the function. After it has run, they point to the +first and last entries in the name-to-number table for the given name, and the +function returns the length of each entry in code units. In both cases, +PCRE2_ERROR_NOSUBSTRING is returned if there are no entries for the given name. +.P +The format of the name table is described +.\" HTML +.\" +above +.\" +in the section entitled \fIInformation about a pattern\fP. Given all the +relevant entries for the name, you can extract each of their numbers, and hence +the captured data. +. +. +.SH "FINDING ALL POSSIBLE MATCHES AT ONE POSITION" +.rs +.sp +The traditional matching function uses a similar algorithm to Perl, which stops +when it finds the first match at a given point in the subject. If you want to +find all possible matches, or the longest possible match at a given position, +consider using the alternative matching function (see below) instead. If you +cannot use the alternative function, you can kludge it up by making use of the +callout facility, which is described in the +.\" HREF +\fBpcre2callout\fP +.\" +documentation. +.P +What you have to do is to insert a callout right at the end of the pattern. +When your callout function is called, extract and save the current matched +substring. Then return 1, which forces \fBpcre2_match()\fP to backtrack and try +other alternatives. Ultimately, when it runs out of matches, +\fBpcre2_match()\fP will yield PCRE2_ERROR_NOMATCH. +. +. +.\" HTML +.SH "MATCHING A PATTERN: THE ALTERNATIVE FUNCTION" +.rs +.sp +.nf +.B int pcre2_dfa_match(const pcre2_code *\fIcode\fP, PCRE2_SPTR \fIsubject\fP, +.B " PCRE2_SIZE \fIlength\fP, PCRE2_SIZE \fIstartoffset\fP," +.B " uint32_t \fIoptions\fP, pcre2_match_data *\fImatch_data\fP," +.B " pcre2_match_context *\fImcontext\fP," +.B " int *\fIworkspace\fP, PCRE2_SIZE \fIwscount\fP);" +.fi +.P +The function \fBpcre2_dfa_match()\fP is called to match a subject string +against a compiled pattern, using a matching algorithm that scans the subject +string just once (not counting lookaround assertions), and does not backtrack. +This has different characteristics to the normal algorithm, and is not +compatible with Perl. Some of the features of PCRE2 patterns are not supported. +Nevertheless, there are times when this kind of matching can be useful. For a +discussion of the two matching algorithms, and a list of features that +\fBpcre2_dfa_match()\fP does not support, see the +.\" HREF +\fBpcre2matching\fP +.\" +documentation. +.P +The arguments for the \fBpcre2_dfa_match()\fP function are the same as for +\fBpcre2_match()\fP, plus two extras. The ovector within the match data block +is used in a different way, and this is described below. The other common +arguments are used in the same way as for \fBpcre2_match()\fP, so their +description is not repeated here. +.P +The two additional arguments provide workspace for the function. The workspace +vector should contain at least 20 elements. It is used for keeping track of +multiple paths through the pattern tree. More workspace is needed for patterns +and subjects where there are a lot of potential matches. +.P +Here is an example of a simple call to \fBpcre2_dfa_match()\fP: +.sp + int wspace[20]; + pcre2_match_data *md = pcre2_match_data_create(4, NULL); + int rc = pcre2_dfa_match( + re, /* result of pcre2_compile() */ + "some string", /* the subject string */ + 11, /* the length of the subject string */ + 0, /* start at offset 0 in the subject */ + 0, /* default options */ + md, /* the match data block */ + NULL, /* a match context; NULL means use defaults */ + wspace, /* working space vector */ + 20); /* number of elements (NOT size in bytes) */ +. +.SS "Option bits for \fBpcre_dfa_match()\fP" +.rs +.sp +The unused bits of the \fIoptions\fP argument for \fBpcre2_dfa_match()\fP must +be zero. The only bits that may be set are PCRE2_ANCHORED, PCRE2_ENDANCHORED, +PCRE2_NOTBOL, PCRE2_NOTEOL, PCRE2_NOTEMPTY, PCRE2_NOTEMPTY_ATSTART, +PCRE2_NO_UTF_CHECK, PCRE2_PARTIAL_HARD, PCRE2_PARTIAL_SOFT, PCRE2_DFA_SHORTEST, +and PCRE2_DFA_RESTART. All but the last four of these are exactly the same as +for \fBpcre2_match()\fP, so their description is not repeated here. +.sp + PCRE2_PARTIAL_HARD + PCRE2_PARTIAL_SOFT +.sp +These have the same general effect as they do for \fBpcre2_match()\fP, but the +details are slightly different. When PCRE2_PARTIAL_HARD is set for +\fBpcre2_dfa_match()\fP, it returns PCRE2_ERROR_PARTIAL if the end of the +subject is reached and there is still at least one matching possibility that +requires additional characters. This happens even if some complete matches have +already been found. When PCRE2_PARTIAL_SOFT is set, the return code +PCRE2_ERROR_NOMATCH is converted into PCRE2_ERROR_PARTIAL if the end of the +subject is reached, there have been no complete matches, but there is still at +least one matching possibility. The portion of the string that was inspected +when the longest partial match was found is set as the first matching string in +both cases. There is a more detailed discussion of partial and multi-segment +matching, with examples, in the +.\" HREF +\fBpcre2partial\fP +.\" +documentation. +.sp + PCRE2_DFA_SHORTEST +.sp +Setting the PCRE2_DFA_SHORTEST option causes the matching algorithm to stop as +soon as it has found one match. Because of the way the alternative algorithm +works, this is necessarily the shortest possible match at the first possible +matching point in the subject string. +.sp + PCRE2_DFA_RESTART +.sp +When \fBpcre2_dfa_match()\fP returns a partial match, it is possible to call it +again, with additional subject characters, and have it continue with the same +match. The PCRE2_DFA_RESTART option requests this action; when it is set, the +\fIworkspace\fP and \fIwscount\fP options must reference the same vector as +before because data about the match so far is left in them after a partial +match. There is more discussion of this facility in the +.\" HREF +\fBpcre2partial\fP +.\" +documentation. +. +. +.SS "Successful returns from \fBpcre2_dfa_match()\fP" +.rs +.sp +When \fBpcre2_dfa_match()\fP succeeds, it may have matched more than one +substring in the subject. Note, however, that all the matches from one run of +the function start at the same point in the subject. The shorter matches are +all initial substrings of the longer matches. For example, if the pattern +.sp + <.*> +.sp +is matched against the string +.sp + This is no more +.sp +the three matched strings are +.sp + + + +.sp +On success, the yield of the function is a number greater than zero, which is +the number of matched substrings. The offsets of the substrings are returned in +the ovector, and can be extracted by number in the same way as for +\fBpcre2_match()\fP, but the numbers bear no relation to any capturing groups +that may exist in the pattern, because DFA matching does not support group +capture. +.P +Calls to the convenience functions that extract substrings by name +return the error PCRE2_ERROR_DFA_UFUNC (unsupported function) if used after a +DFA match. The convenience functions that extract substrings by number never +return PCRE2_ERROR_NOSUBSTRING. +.P +The matched strings are stored in the ovector in reverse order of length; that +is, the longest matching string is first. If there were too many matches to fit +into the ovector, the yield of the function is zero, and the vector is filled +with the longest matches. +.P +NOTE: PCRE2's "auto-possessification" optimization usually applies to character +repeats at the end of a pattern (as well as internally). For example, the +pattern "a\ed+" is compiled as if it were "a\ed++". For DFA matching, this +means that only one possible match is found. If you really do want multiple +matches in such cases, either use an ungreedy repeat such as "a\ed+?" or set +the PCRE2_NO_AUTO_POSSESS option when compiling. +. +. +.SS "Error returns from \fBpcre2_dfa_match()\fP" +.rs +.sp +The \fBpcre2_dfa_match()\fP function returns a negative number when it fails. +Many of the errors are the same as for \fBpcre2_match()\fP, as described +.\" HTML +.\" +above. +.\" +There are in addition the following errors that are specific to +\fBpcre2_dfa_match()\fP: +.sp + PCRE2_ERROR_DFA_UITEM +.sp +This return is given if \fBpcre2_dfa_match()\fP encounters an item in the +pattern that it does not support, for instance, the use of \eC in a UTF mode or +a backreference. +.sp + PCRE2_ERROR_DFA_UCOND +.sp +This return is given if \fBpcre2_dfa_match()\fP encounters a condition item +that uses a backreference for the condition, or a test for recursion in a +specific group. These are not supported. +.sp + PCRE2_ERROR_DFA_WSSIZE +.sp +This return is given if \fBpcre2_dfa_match()\fP runs out of space in the +\fIworkspace\fP vector. +.sp + PCRE2_ERROR_DFA_RECURSE +.sp +When a recursive subpattern is processed, the matching function calls itself +recursively, using private memory for the ovector and \fIworkspace\fP. This +error is given if the internal ovector is not large enough. This should be +extremely rare, as a vector of size 1000 is used. +.sp + PCRE2_ERROR_DFA_BADRESTART +.sp +When \fBpcre2_dfa_match()\fP is called with the \fBPCRE2_DFA_RESTART\fP option, +some plausibility checks are made on the contents of the workspace, which +should contain data about the previous partial match. If any of these checks +fail, this error is given. +. +. +.SH "SEE ALSO" +.rs +.sp +\fBpcre2build\fP(3), \fBpcre2callout\fP(3), \fBpcre2demo(3)\fP, +\fBpcre2matching\fP(3), \fBpcre2partial\fP(3), \fBpcre2posix\fP(3), +\fBpcre2sample\fP(3), \fBpcre2unicode\fP(3). +. +. +.SH AUTHOR +.rs +.sp +.nf +Philip Hazel +University Computing Service +Cambridge, England. +.fi +. +. +.SH REVISION +.rs +.sp +.nf +Last updated: 07 September 2018 +Copyright (c) 1997-2018 University of Cambridge. +.fi