1*22dc650dSSadaf Ebrahimi<html> 2*22dc650dSSadaf Ebrahimi<head> 3*22dc650dSSadaf Ebrahimi<title>pcre2posix specification</title> 4*22dc650dSSadaf Ebrahimi</head> 5*22dc650dSSadaf Ebrahimi<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB"> 6*22dc650dSSadaf Ebrahimi<h1>pcre2posix man page</h1> 7*22dc650dSSadaf Ebrahimi<p> 8*22dc650dSSadaf EbrahimiReturn to the <a href="index.html">PCRE2 index page</a>. 9*22dc650dSSadaf Ebrahimi</p> 10*22dc650dSSadaf Ebrahimi<p> 11*22dc650dSSadaf EbrahimiThis page is part of the PCRE2 HTML documentation. It was generated 12*22dc650dSSadaf Ebrahimiautomatically from the original man page. If there is any nonsense in it, 13*22dc650dSSadaf Ebrahimiplease consult the man page, in case the conversion went wrong. 14*22dc650dSSadaf Ebrahimi<br> 15*22dc650dSSadaf Ebrahimi<ul> 16*22dc650dSSadaf Ebrahimi<li><a name="TOC1" href="#SEC1">SYNOPSIS</a> 17*22dc650dSSadaf Ebrahimi<li><a name="TOC2" href="#SEC2">DESCRIPTION</a> 18*22dc650dSSadaf Ebrahimi<li><a name="TOC3" href="#SEC3">USING THE POSIX FUNCTIONS</a> 19*22dc650dSSadaf Ebrahimi<li><a name="TOC4" href="#SEC4">COMPILING A PATTERN</a> 20*22dc650dSSadaf Ebrahimi<li><a name="TOC5" href="#SEC5">MATCHING NEWLINE CHARACTERS</a> 21*22dc650dSSadaf Ebrahimi<li><a name="TOC6" href="#SEC6">MATCHING A PATTERN</a> 22*22dc650dSSadaf Ebrahimi<li><a name="TOC7" href="#SEC7">ERROR MESSAGES</a> 23*22dc650dSSadaf Ebrahimi<li><a name="TOC8" href="#SEC8">MEMORY USAGE</a> 24*22dc650dSSadaf Ebrahimi<li><a name="TOC9" href="#SEC9">AUTHOR</a> 25*22dc650dSSadaf Ebrahimi<li><a name="TOC10" href="#SEC10">REVISION</a> 26*22dc650dSSadaf Ebrahimi</ul> 27*22dc650dSSadaf Ebrahimi<br><a name="SEC1" href="#TOC1">SYNOPSIS</a><br> 28*22dc650dSSadaf Ebrahimi<P> 29*22dc650dSSadaf Ebrahimi<b>#include <pcre2posix.h></b> 30*22dc650dSSadaf Ebrahimi</P> 31*22dc650dSSadaf Ebrahimi<P> 32*22dc650dSSadaf Ebrahimi<b>int pcre2_regcomp(regex_t *<i>preg</i>, const char *<i>pattern</i>,</b> 33*22dc650dSSadaf Ebrahimi<b> int <i>cflags</i>);</b> 34*22dc650dSSadaf Ebrahimi<br> 35*22dc650dSSadaf Ebrahimi<br> 36*22dc650dSSadaf Ebrahimi<b>int pcre2_regexec(const regex_t *<i>preg</i>, const char *<i>string</i>,</b> 37*22dc650dSSadaf Ebrahimi<b> size_t <i>nmatch</i>, regmatch_t <i>pmatch</i>[], int <i>eflags</i>);</b> 38*22dc650dSSadaf Ebrahimi<br> 39*22dc650dSSadaf Ebrahimi<br> 40*22dc650dSSadaf Ebrahimi<b>size_t pcre2_regerror(int <i>errcode</i>, const regex_t *<i>preg</i>,</b> 41*22dc650dSSadaf Ebrahimi<b> char *<i>errbuf</i>, size_t <i>errbuf_size</i>);</b> 42*22dc650dSSadaf Ebrahimi<br> 43*22dc650dSSadaf Ebrahimi<br> 44*22dc650dSSadaf Ebrahimi<b>void pcre2_regfree(regex_t *<i>preg</i>);</b> 45*22dc650dSSadaf Ebrahimi</P> 46*22dc650dSSadaf Ebrahimi<br><a name="SEC2" href="#TOC1">DESCRIPTION</a><br> 47*22dc650dSSadaf Ebrahimi<P> 48*22dc650dSSadaf EbrahimiThis set of functions provides a POSIX-style API for the PCRE2 regular 49*22dc650dSSadaf Ebrahimiexpression 8-bit library. There are no POSIX-style wrappers for PCRE2's 16-bit 50*22dc650dSSadaf Ebrahimiand 32-bit libraries. See the 51*22dc650dSSadaf Ebrahimi<a href="pcre2api.html"><b>pcre2api</b></a> 52*22dc650dSSadaf Ebrahimidocumentation for a description of PCRE2's native API, which contains much 53*22dc650dSSadaf Ebrahimiadditional functionality. 54*22dc650dSSadaf Ebrahimi</P> 55*22dc650dSSadaf Ebrahimi<P> 56*22dc650dSSadaf Ebrahimi<b>IMPORTANT NOTE</b>: The functions described here are NOT thread-safe, and 57*22dc650dSSadaf Ebrahimishould not be used in multi-threaded applications. They are also limited to 58*22dc650dSSadaf Ebrahimiprocessing subjects that are not bigger than 2GB. Use the native API instead. 59*22dc650dSSadaf Ebrahimi</P> 60*22dc650dSSadaf Ebrahimi<P> 61*22dc650dSSadaf EbrahimiThese functions are wrapper functions that ultimately call the PCRE2 native 62*22dc650dSSadaf EbrahimiAPI. Their prototypes are defined in the <b>pcre2posix.h</b> header file, and 63*22dc650dSSadaf Ebrahimithey all have unique names starting with <b>pcre2_</b>. However, the 64*22dc650dSSadaf Ebrahimi<b>pcre2posix.h</b> header also contains macro definitions that convert the 65*22dc650dSSadaf Ebrahimistandard POSIX names such <b>regcomp()</b> into <b>pcre2_regcomp()</b> etc. This 66*22dc650dSSadaf Ebrahimimeans that a program can use the usual POSIX names without running the risk of 67*22dc650dSSadaf Ebrahimiaccidentally linking with POSIX functions from a different library. 68*22dc650dSSadaf Ebrahimi</P> 69*22dc650dSSadaf Ebrahimi<P> 70*22dc650dSSadaf EbrahimiOn Unix-like systems the PCRE2 POSIX library is called <b>libpcre2-posix</b>, so 71*22dc650dSSadaf Ebrahimican be accessed by adding <b>-lpcre2-posix</b> to the command for linking an 72*22dc650dSSadaf Ebrahimiapplication. Because the POSIX functions call the native ones, it is also 73*22dc650dSSadaf Ebrahiminecessary to add <b>-lpcre2-8</b>. 74*22dc650dSSadaf Ebrahimi</P> 75*22dc650dSSadaf Ebrahimi<P> 76*22dc650dSSadaf EbrahimiOn Windows systems, if you are linking to a DLL version of the library, it is 77*22dc650dSSadaf Ebrahimirecommended that <b>PCRE2POSIX_SHARED</b> is defined before including the 78*22dc650dSSadaf Ebrahimi<b>pcre2posix.h</b> header, as it will allow for a more efficient way to 79*22dc650dSSadaf Ebrahimiinvoke the functions by adding the <b>__declspec(dllimport)</b> decorator. 80*22dc650dSSadaf Ebrahimi</P> 81*22dc650dSSadaf Ebrahimi<P> 82*22dc650dSSadaf EbrahimiAlthough they were not defined as prototypes in <b>pcre2posix.h</b>, releases 83*22dc650dSSadaf Ebrahimi10.33 to 10.36 of the library contained functions with the POSIX names 84*22dc650dSSadaf Ebrahimi<b>regcomp()</b> etc. These simply passed their arguments to the PCRE2 85*22dc650dSSadaf Ebrahimifunctions. These functions were provided for backwards compatibility with 86*22dc650dSSadaf Ebrahimiearlier versions of PCRE2, which had only POSIX names. However, this has proved 87*22dc650dSSadaf Ebrahimitroublesome in situations where a program links with several libraries, some of 88*22dc650dSSadaf Ebrahimiwhich use PCRE2's POSIX interface while others use the real POSIX functions. 89*22dc650dSSadaf EbrahimiFor this reason, the POSIX names have been removed since release 10.37. 90*22dc650dSSadaf Ebrahimi</P> 91*22dc650dSSadaf Ebrahimi<P> 92*22dc650dSSadaf EbrahimiCalling the header file <b>pcre2posix.h</b> avoids any conflict with other POSIX 93*22dc650dSSadaf Ebrahimilibraries. It can, of course, be renamed or aliased as <b>regex.h</b>, which is 94*22dc650dSSadaf Ebrahimithe "correct" name, if there is no clash. It provides two structure types, 95*22dc650dSSadaf Ebrahimi<i>regex_t</i> for compiled internal forms, and <i>regmatch_t</i> for returning 96*22dc650dSSadaf Ebrahimicaptured substrings. It also defines some constants whose names start with 97*22dc650dSSadaf Ebrahimi"REG_"; these are used for setting options and identifying error codes. 98*22dc650dSSadaf Ebrahimi</P> 99*22dc650dSSadaf Ebrahimi<br><a name="SEC3" href="#TOC1">USING THE POSIX FUNCTIONS</a><br> 100*22dc650dSSadaf Ebrahimi<P> 101*22dc650dSSadaf EbrahimiNote that these functions are just POSIX-style wrappers for PCRE2's native API. 102*22dc650dSSadaf EbrahimiThey do not give POSIX regular expression behaviour, and they are not 103*22dc650dSSadaf Ebrahimithread-safe or even POSIX compatible. 104*22dc650dSSadaf Ebrahimi</P> 105*22dc650dSSadaf Ebrahimi<P> 106*22dc650dSSadaf EbrahimiThose POSIX option bits that can reasonably be mapped to PCRE2 native options 107*22dc650dSSadaf Ebrahimihave been implemented. In addition, the option REG_EXTENDED is defined with the 108*22dc650dSSadaf Ebrahimivalue zero. This has no effect, but since programs that are written to the 109*22dc650dSSadaf EbrahimiPOSIX interface often use it, this makes it easier to slot in PCRE2 as a 110*22dc650dSSadaf Ebrahimireplacement library. Other POSIX options are not even defined. 111*22dc650dSSadaf Ebrahimi</P> 112*22dc650dSSadaf Ebrahimi<P> 113*22dc650dSSadaf EbrahimiThere are also some options that are not defined by POSIX. These have been 114*22dc650dSSadaf Ebrahimiadded at the request of users who want to make use of certain PCRE2-specific 115*22dc650dSSadaf Ebrahimifeatures via the POSIX calling interface or to add BSD or GNU functionality. 116*22dc650dSSadaf Ebrahimi</P> 117*22dc650dSSadaf Ebrahimi<P> 118*22dc650dSSadaf EbrahimiWhen PCRE2 is called via these functions, it is only the API that is POSIX-like 119*22dc650dSSadaf Ebrahimiin style. The syntax and semantics of the regular expressions themselves are 120*22dc650dSSadaf Ebrahimistill those of Perl, subject to the setting of various PCRE2 options, as 121*22dc650dSSadaf Ebrahimidescribed below. "POSIX-like in style" means that the API approximates to the 122*22dc650dSSadaf EbrahimiPOSIX definition; it is not fully POSIX-compatible, and in multi-unit encoding 123*22dc650dSSadaf Ebrahimidomains it is probably even less compatible. 124*22dc650dSSadaf Ebrahimi</P> 125*22dc650dSSadaf Ebrahimi<P> 126*22dc650dSSadaf EbrahimiThe descriptions below use the actual names of the functions, but, as described 127*22dc650dSSadaf Ebrahimiabove, the standard POSIX names (without the <b>pcre2_</b> prefix) may also be 128*22dc650dSSadaf Ebrahimiused. 129*22dc650dSSadaf Ebrahimi</P> 130*22dc650dSSadaf Ebrahimi<br><a name="SEC4" href="#TOC1">COMPILING A PATTERN</a><br> 131*22dc650dSSadaf Ebrahimi<P> 132*22dc650dSSadaf EbrahimiThe function <b>pcre2_regcomp()</b> is called to compile a pattern into an 133*22dc650dSSadaf Ebrahimiinternal form. By default, the pattern is a C string terminated by a binary 134*22dc650dSSadaf Ebrahimizero (but see REG_PEND below). The <i>preg</i> argument is a pointer to a 135*22dc650dSSadaf Ebrahimi<b>regex_t</b> structure that is used as a base for storing information about 136*22dc650dSSadaf Ebrahimithe compiled regular expression. It is also used for input when REG_PEND is 137*22dc650dSSadaf Ebrahimiset. The <b>regex_t</b> structure used by <b>pcre2_regcomp()</b> is defined in 138*22dc650dSSadaf Ebrahimi<b>pcre2posix.h</b> and is not the same as the structure used by other libraries 139*22dc650dSSadaf Ebrahimithat provide POSIX-style matching. 140*22dc650dSSadaf Ebrahimi</P> 141*22dc650dSSadaf Ebrahimi<P> 142*22dc650dSSadaf EbrahimiThe argument <i>cflags</i> is either zero, or contains one or more of the bits 143*22dc650dSSadaf Ebrahimidefined by the following macros: 144*22dc650dSSadaf Ebrahimi<pre> 145*22dc650dSSadaf Ebrahimi REG_DOTALL 146*22dc650dSSadaf Ebrahimi</pre> 147*22dc650dSSadaf EbrahimiThe PCRE2_DOTALL option is set when the regular expression is passed for 148*22dc650dSSadaf Ebrahimicompilation to the native function. Note that REG_DOTALL is not part of the 149*22dc650dSSadaf EbrahimiPOSIX standard. 150*22dc650dSSadaf Ebrahimi<pre> 151*22dc650dSSadaf Ebrahimi REG_ICASE 152*22dc650dSSadaf Ebrahimi</pre> 153*22dc650dSSadaf EbrahimiThe PCRE2_CASELESS option is set when the regular expression is passed for 154*22dc650dSSadaf Ebrahimicompilation to the native function. 155*22dc650dSSadaf Ebrahimi<pre> 156*22dc650dSSadaf Ebrahimi REG_NEWLINE 157*22dc650dSSadaf Ebrahimi</pre> 158*22dc650dSSadaf EbrahimiThe PCRE2_MULTILINE option is set when the regular expression is passed for 159*22dc650dSSadaf Ebrahimicompilation to the native function. Note that this does <i>not</i> mimic the 160*22dc650dSSadaf Ebrahimidefined POSIX behaviour for REG_NEWLINE (see the following section). 161*22dc650dSSadaf Ebrahimi<pre> 162*22dc650dSSadaf Ebrahimi REG_NOSPEC 163*22dc650dSSadaf Ebrahimi</pre> 164*22dc650dSSadaf EbrahimiThe PCRE2_LITERAL option is set when the regular expression is passed for 165*22dc650dSSadaf Ebrahimicompilation to the native function. This disables all meta characters in the 166*22dc650dSSadaf Ebrahimipattern, causing it to be treated as a literal string. The only other options 167*22dc650dSSadaf Ebrahimithat are allowed with REG_NOSPEC are REG_ICASE, REG_NOSUB, REG_PEND, and 168*22dc650dSSadaf EbrahimiREG_UTF. Note that REG_NOSPEC is not part of the POSIX standard. 169*22dc650dSSadaf Ebrahimi<pre> 170*22dc650dSSadaf Ebrahimi REG_NOSUB 171*22dc650dSSadaf Ebrahimi</pre> 172*22dc650dSSadaf EbrahimiWhen a pattern that is compiled with this flag is passed to 173*22dc650dSSadaf Ebrahimi<b>pcre2_regexec()</b> for matching, the <i>nmatch</i> and <i>pmatch</i> arguments 174*22dc650dSSadaf Ebrahimiare ignored, and no captured strings are returned. Versions of the PCRE library 175*22dc650dSSadaf Ebrahimiprior to 10.22 used to set the PCRE2_NO_AUTO_CAPTURE compile option, but this 176*22dc650dSSadaf Ebrahimino longer happens because it disables the use of backreferences. 177*22dc650dSSadaf Ebrahimi<pre> 178*22dc650dSSadaf Ebrahimi REG_PEND 179*22dc650dSSadaf Ebrahimi</pre> 180*22dc650dSSadaf EbrahimiIf this option is set, the <b>reg_endp</b> field in the <i>preg</i> structure 181*22dc650dSSadaf Ebrahimi(which has the type const char *) must be set to point to the character beyond 182*22dc650dSSadaf Ebrahimithe end of the pattern before calling <b>pcre2_regcomp()</b>. The pattern itself 183*22dc650dSSadaf Ebrahimimay now contain binary zeros, which are treated as data characters. Without 184*22dc650dSSadaf EbrahimiREG_PEND, a binary zero terminates the pattern and the <b>re_endp</b> field is 185*22dc650dSSadaf Ebrahimiignored. This is a GNU extension to the POSIX standard and should be used with 186*22dc650dSSadaf Ebrahimicaution in software intended to be portable to other systems. 187*22dc650dSSadaf Ebrahimi<pre> 188*22dc650dSSadaf Ebrahimi REG_UCP 189*22dc650dSSadaf Ebrahimi</pre> 190*22dc650dSSadaf EbrahimiThe PCRE2_UCP option is set when the regular expression is passed for 191*22dc650dSSadaf Ebrahimicompilation to the native function. This causes PCRE2 to use Unicode properties 192*22dc650dSSadaf Ebrahimiwhen matching \d, \w, etc., instead of just recognizing ASCII values. Note 193*22dc650dSSadaf Ebrahimithat REG_UCP is not part of the POSIX standard. 194*22dc650dSSadaf Ebrahimi<pre> 195*22dc650dSSadaf Ebrahimi REG_UNGREEDY 196*22dc650dSSadaf Ebrahimi</pre> 197*22dc650dSSadaf EbrahimiThe PCRE2_UNGREEDY option is set when the regular expression is passed for 198*22dc650dSSadaf Ebrahimicompilation to the native function. Note that REG_UNGREEDY is not part of the 199*22dc650dSSadaf EbrahimiPOSIX standard. 200*22dc650dSSadaf Ebrahimi<pre> 201*22dc650dSSadaf Ebrahimi REG_UTF 202*22dc650dSSadaf Ebrahimi</pre> 203*22dc650dSSadaf EbrahimiThe PCRE2_UTF option is set when the regular expression is passed for 204*22dc650dSSadaf Ebrahimicompilation to the native function. This causes the pattern itself and all data 205*22dc650dSSadaf Ebrahimistrings used for matching it to be treated as UTF-8 strings. Note that REG_UTF 206*22dc650dSSadaf Ebrahimiis not part of the POSIX standard. 207*22dc650dSSadaf Ebrahimi</P> 208*22dc650dSSadaf Ebrahimi<P> 209*22dc650dSSadaf EbrahimiIn the absence of these flags, no options are passed to the native function. 210*22dc650dSSadaf EbrahimiThis means that the regex is compiled with PCRE2 default semantics. In 211*22dc650dSSadaf Ebrahimiparticular, the way it handles newline characters in the subject string is the 212*22dc650dSSadaf EbrahimiPerl way, not the POSIX way. Note that setting PCRE2_MULTILINE has only 213*22dc650dSSadaf Ebrahimi<i>some</i> of the effects specified for REG_NEWLINE. It does not affect the way 214*22dc650dSSadaf Ebrahiminewlines are matched by the dot metacharacter (they are not) or by a negative 215*22dc650dSSadaf Ebrahimiclass such as [^a] (they are). 216*22dc650dSSadaf Ebrahimi</P> 217*22dc650dSSadaf Ebrahimi<P> 218*22dc650dSSadaf EbrahimiThe yield of <b>pcre2_regcomp()</b> is zero on success, and non-zero otherwise. 219*22dc650dSSadaf EbrahimiThe <i>preg</i> structure is filled in on success, and one other member of the 220*22dc650dSSadaf Ebrahimistructure (as well as <i>re_endp</i>) is public: <i>re_nsub</i> contains the 221*22dc650dSSadaf Ebrahiminumber of capturing subpatterns in the regular expression. Various error codes 222*22dc650dSSadaf Ebrahimiare defined in the header file. 223*22dc650dSSadaf Ebrahimi</P> 224*22dc650dSSadaf Ebrahimi<P> 225*22dc650dSSadaf EbrahimiNOTE: If the yield of <b>pcre2_regcomp()</b> is non-zero, you must not attempt 226*22dc650dSSadaf Ebrahimito use the contents of the <i>preg</i> structure. If, for example, you pass it 227*22dc650dSSadaf Ebrahimito <b>pcre2_regexec()</b>, the result is undefined and your program is likely to 228*22dc650dSSadaf Ebrahimicrash. 229*22dc650dSSadaf Ebrahimi</P> 230*22dc650dSSadaf Ebrahimi<br><a name="SEC5" href="#TOC1">MATCHING NEWLINE CHARACTERS</a><br> 231*22dc650dSSadaf Ebrahimi<P> 232*22dc650dSSadaf EbrahimiThis area is not simple, because POSIX and Perl take different views of things. 233*22dc650dSSadaf EbrahimiIt is not possible to get PCRE2 to obey POSIX semantics, but then PCRE2 was 234*22dc650dSSadaf Ebrahiminever intended to be a POSIX engine. The following table lists the different 235*22dc650dSSadaf Ebrahimipossibilities for matching newline characters in Perl and PCRE2: 236*22dc650dSSadaf Ebrahimi<pre> 237*22dc650dSSadaf Ebrahimi Default Change with 238*22dc650dSSadaf Ebrahimi 239*22dc650dSSadaf Ebrahimi . matches newline no PCRE2_DOTALL 240*22dc650dSSadaf Ebrahimi newline matches [^a] yes not changeable 241*22dc650dSSadaf Ebrahimi $ matches \n at end yes PCRE2_DOLLAR_ENDONLY 242*22dc650dSSadaf Ebrahimi $ matches \n in middle no PCRE2_MULTILINE 243*22dc650dSSadaf Ebrahimi ^ matches \n in middle no PCRE2_MULTILINE 244*22dc650dSSadaf Ebrahimi</pre> 245*22dc650dSSadaf EbrahimiThis is the equivalent table for a POSIX-compatible pattern matcher: 246*22dc650dSSadaf Ebrahimi<pre> 247*22dc650dSSadaf Ebrahimi Default Change with 248*22dc650dSSadaf Ebrahimi 249*22dc650dSSadaf Ebrahimi . matches newline yes REG_NEWLINE 250*22dc650dSSadaf Ebrahimi newline matches [^a] yes REG_NEWLINE 251*22dc650dSSadaf Ebrahimi $ matches \n at end no REG_NEWLINE 252*22dc650dSSadaf Ebrahimi $ matches \n in middle no REG_NEWLINE 253*22dc650dSSadaf Ebrahimi ^ matches \n in middle no REG_NEWLINE 254*22dc650dSSadaf Ebrahimi</pre> 255*22dc650dSSadaf EbrahimiThis behaviour is not what happens when PCRE2 is called via its POSIX 256*22dc650dSSadaf EbrahimiAPI. By default, PCRE2's behaviour is the same as Perl's, except that there is 257*22dc650dSSadaf Ebrahimino equivalent for PCRE2_DOLLAR_ENDONLY in Perl. In both PCRE2 and Perl, there 258*22dc650dSSadaf Ebrahimiis no way to stop newline from matching [^a]. 259*22dc650dSSadaf Ebrahimi</P> 260*22dc650dSSadaf Ebrahimi<P> 261*22dc650dSSadaf EbrahimiDefault POSIX newline handling can be obtained by setting PCRE2_DOTALL and 262*22dc650dSSadaf EbrahimiPCRE2_DOLLAR_ENDONLY when calling <b>pcre2_compile()</b> directly, but there is 263*22dc650dSSadaf Ebrahimino way to make PCRE2 behave exactly as for the REG_NEWLINE action. When using 264*22dc650dSSadaf Ebrahimithe POSIX API, passing REG_NEWLINE to PCRE2's <b>pcre2_regcomp()</b> function 265*22dc650dSSadaf Ebrahimicauses PCRE2_MULTILINE to be passed to <b>pcre2_compile()</b>, and REG_DOTALL 266*22dc650dSSadaf Ebrahimipasses PCRE2_DOTALL. There is no way to pass PCRE2_DOLLAR_ENDONLY. 267*22dc650dSSadaf Ebrahimi</P> 268*22dc650dSSadaf Ebrahimi<br><a name="SEC6" href="#TOC1">MATCHING A PATTERN</a><br> 269*22dc650dSSadaf Ebrahimi<P> 270*22dc650dSSadaf EbrahimiThe function <b>pcre2_regexec()</b> is called to match a compiled pattern 271*22dc650dSSadaf Ebrahimi<i>preg</i> against a given <i>string</i>, which is by default terminated by a 272*22dc650dSSadaf Ebrahimizero byte (but see REG_STARTEND below), subject to the options in <i>eflags</i>. 273*22dc650dSSadaf EbrahimiThese can be: 274*22dc650dSSadaf Ebrahimi<pre> 275*22dc650dSSadaf Ebrahimi REG_NOTBOL 276*22dc650dSSadaf Ebrahimi</pre> 277*22dc650dSSadaf EbrahimiThe PCRE2_NOTBOL option is set when calling the underlying PCRE2 matching 278*22dc650dSSadaf Ebrahimifunction. 279*22dc650dSSadaf Ebrahimi<pre> 280*22dc650dSSadaf Ebrahimi REG_NOTEMPTY 281*22dc650dSSadaf Ebrahimi</pre> 282*22dc650dSSadaf EbrahimiThe PCRE2_NOTEMPTY option is set when calling the underlying PCRE2 matching 283*22dc650dSSadaf Ebrahimifunction. Note that REG_NOTEMPTY is not part of the POSIX standard. However, 284*22dc650dSSadaf Ebrahimisetting this option can give more POSIX-like behaviour in some situations. 285*22dc650dSSadaf Ebrahimi<pre> 286*22dc650dSSadaf Ebrahimi REG_NOTEOL 287*22dc650dSSadaf Ebrahimi</pre> 288*22dc650dSSadaf EbrahimiThe PCRE2_NOTEOL option is set when calling the underlying PCRE2 matching 289*22dc650dSSadaf Ebrahimifunction. 290*22dc650dSSadaf Ebrahimi<pre> 291*22dc650dSSadaf Ebrahimi REG_STARTEND 292*22dc650dSSadaf Ebrahimi</pre> 293*22dc650dSSadaf EbrahimiWhen this option is set, the subject string starts at <i>string</i> + 294*22dc650dSSadaf Ebrahimi<i>pmatch[0].rm_so</i> and ends at <i>string</i> + <i>pmatch[0].rm_eo</i>, which 295*22dc650dSSadaf Ebrahimishould point to the first character beyond the string. There may be binary 296*22dc650dSSadaf Ebrahimizeros within the subject string, and indeed, using REG_STARTEND is the only 297*22dc650dSSadaf Ebrahimiway to pass a subject string that contains a binary zero. 298*22dc650dSSadaf Ebrahimi</P> 299*22dc650dSSadaf Ebrahimi<P> 300*22dc650dSSadaf EbrahimiWhatever the value of <i>pmatch[0].rm_so</i>, the offsets of the matched string 301*22dc650dSSadaf Ebrahimiand any captured substrings are still given relative to the start of 302*22dc650dSSadaf Ebrahimi<i>string</i> itself. (Before PCRE2 release 10.30 these were given relative to 303*22dc650dSSadaf Ebrahimi<i>string</i> + <i>pmatch[0].rm_so</i>, but this differs from other 304*22dc650dSSadaf Ebrahimiimplementations.) 305*22dc650dSSadaf Ebrahimi</P> 306*22dc650dSSadaf Ebrahimi<P> 307*22dc650dSSadaf EbrahimiThis is a BSD extension, compatible with but not specified by IEEE Standard 308*22dc650dSSadaf Ebrahimi1003.2 (POSIX.2), and should be used with caution in software intended to be 309*22dc650dSSadaf Ebrahimiportable to other systems. Note that a non-zero <i>rm_so</i> does not imply 310*22dc650dSSadaf EbrahimiREG_NOTBOL; REG_STARTEND affects only the location and length of the string, 311*22dc650dSSadaf Ebrahiminot how it is matched. Setting REG_STARTEND and passing <i>pmatch</i> as NULL 312*22dc650dSSadaf Ebrahimiare mutually exclusive; the error REG_INVARG is returned. 313*22dc650dSSadaf Ebrahimi</P> 314*22dc650dSSadaf Ebrahimi<P> 315*22dc650dSSadaf EbrahimiIf the pattern was compiled with the REG_NOSUB flag, no data about any matched 316*22dc650dSSadaf Ebrahimistrings is returned. The <i>nmatch</i> and <i>pmatch</i> arguments of 317*22dc650dSSadaf Ebrahimi<b>pcre2_regexec()</b> are ignored (except possibly as input for REG_STARTEND). 318*22dc650dSSadaf Ebrahimi</P> 319*22dc650dSSadaf Ebrahimi<P> 320*22dc650dSSadaf EbrahimiThe value of <i>nmatch</i> may be zero, and the value <i>pmatch</i> may be NULL 321*22dc650dSSadaf Ebrahimi(unless REG_STARTEND is set); in both these cases no data about any matched 322*22dc650dSSadaf Ebrahimistrings is returned. 323*22dc650dSSadaf Ebrahimi</P> 324*22dc650dSSadaf Ebrahimi<P> 325*22dc650dSSadaf EbrahimiOtherwise, the portion of the string that was matched, and also any captured 326*22dc650dSSadaf Ebrahimisubstrings, are returned via the <i>pmatch</i> argument, which points to an 327*22dc650dSSadaf Ebrahimiarray of <i>nmatch</i> structures of type <i>regmatch_t</i>, containing the 328*22dc650dSSadaf Ebrahimimembers <i>rm_so</i> and <i>rm_eo</i>. These contain the byte offset to the first 329*22dc650dSSadaf Ebrahimicharacter of each substring and the offset to the first character after the end 330*22dc650dSSadaf Ebrahimiof each substring, respectively. The 0th element of the vector relates to the 331*22dc650dSSadaf Ebrahimientire portion of <i>string</i> that was matched; subsequent elements relate to 332*22dc650dSSadaf Ebrahimithe capturing subpatterns of the regular expression. Unused entries in the 333*22dc650dSSadaf Ebrahimiarray have both structure members set to -1. 334*22dc650dSSadaf Ebrahimi</P> 335*22dc650dSSadaf Ebrahimi<P> 336*22dc650dSSadaf Ebrahimi<i>regmatch_t</i> as well as the <i>regoff_t</i> typedef it uses are defined in 337*22dc650dSSadaf Ebrahimi<b>pcre2posix.h</b> and are not warranted to have the same size or layout as other 338*22dc650dSSadaf Ebrahimisimilarly named types from other libraries that provide POSIX-style matching. 339*22dc650dSSadaf Ebrahimi</P> 340*22dc650dSSadaf Ebrahimi<P> 341*22dc650dSSadaf EbrahimiA successful match yields a zero return; various error codes are defined in the 342*22dc650dSSadaf Ebrahimiheader file, of which REG_NOMATCH is the "expected" failure code. 343*22dc650dSSadaf Ebrahimi</P> 344*22dc650dSSadaf Ebrahimi<br><a name="SEC7" href="#TOC1">ERROR MESSAGES</a><br> 345*22dc650dSSadaf Ebrahimi<P> 346*22dc650dSSadaf EbrahimiThe <b>pcre2_regerror()</b> function maps a non-zero errorcode from either 347*22dc650dSSadaf Ebrahimi<b>pcre2_regcomp()</b> or <b>pcre2_regexec()</b> to a printable message. If 348*22dc650dSSadaf Ebrahimi<i>preg</i> is not NULL, the error should have arisen from the use of that 349*22dc650dSSadaf Ebrahimistructure. A message terminated by a binary zero is placed in <i>errbuf</i>. If 350*22dc650dSSadaf Ebrahimithe buffer is too short, only the first <i>errbuf_size</i> - 1 characters of the 351*22dc650dSSadaf Ebrahimierror message are used. The yield of the function is the size of buffer needed 352*22dc650dSSadaf Ebrahimito hold the whole message, including the terminating zero. This value is 353*22dc650dSSadaf Ebrahimigreater than <i>errbuf_size</i> if the message was truncated. 354*22dc650dSSadaf Ebrahimi</P> 355*22dc650dSSadaf Ebrahimi<br><a name="SEC8" href="#TOC1">MEMORY USAGE</a><br> 356*22dc650dSSadaf Ebrahimi<P> 357*22dc650dSSadaf EbrahimiCompiling a regular expression causes memory to be allocated and associated 358*22dc650dSSadaf Ebrahimiwith the <i>preg</i> structure. The function <b>pcre2_regfree()</b> frees all 359*22dc650dSSadaf Ebrahimisuch memory, after which <i>preg</i> may no longer be used as a compiled 360*22dc650dSSadaf Ebrahimiexpression. 361*22dc650dSSadaf Ebrahimi</P> 362*22dc650dSSadaf Ebrahimi<br><a name="SEC9" href="#TOC1">AUTHOR</a><br> 363*22dc650dSSadaf Ebrahimi<P> 364*22dc650dSSadaf EbrahimiPhilip Hazel 365*22dc650dSSadaf Ebrahimi<br> 366*22dc650dSSadaf EbrahimiRetired from University Computing Service 367*22dc650dSSadaf Ebrahimi<br> 368*22dc650dSSadaf EbrahimiCambridge, England. 369*22dc650dSSadaf Ebrahimi<br> 370*22dc650dSSadaf Ebrahimi</P> 371*22dc650dSSadaf Ebrahimi<br><a name="SEC10" href="#TOC1">REVISION</a><br> 372*22dc650dSSadaf Ebrahimi<P> 373*22dc650dSSadaf EbrahimiLast updated: 19 January 2024 374*22dc650dSSadaf Ebrahimi<br> 375*22dc650dSSadaf EbrahimiCopyright © 1997-2024 University of Cambridge. 376*22dc650dSSadaf Ebrahimi<br> 377*22dc650dSSadaf Ebrahimi<p> 378*22dc650dSSadaf EbrahimiReturn to the <a href="index.html">PCRE2 index page</a>. 379*22dc650dSSadaf Ebrahimi</p> 380