1<html> 2<head> 3<title>pcreapi specification</title> 4</head> 5<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB"> 6<h1>pcreapi man page</h1> 7<p> 8Return to the <a href="index.html">PCRE index page</a>. 9</p> 10<p> 11This page is part of the PCRE HTML documentation. It was generated automatically 12from the original man page. If there is any nonsense in it, please consult the 13man page, in case the conversion went wrong. 14<br> 15<ul> 16<li><a name="TOC1" href="#SEC1">PCRE NATIVE API BASIC FUNCTIONS</a> 17<li><a name="TOC2" href="#SEC2">PCRE NATIVE API STRING EXTRACTION FUNCTIONS</a> 18<li><a name="TOC3" href="#SEC3">PCRE NATIVE API AUXILIARY FUNCTIONS</a> 19<li><a name="TOC4" href="#SEC4">PCRE NATIVE API INDIRECTED FUNCTIONS</a> 20<li><a name="TOC5" href="#SEC5">PCRE 8-BIT AND 16-BIT LIBRARIES</a> 21<li><a name="TOC6" href="#SEC6">PCRE API OVERVIEW</a> 22<li><a name="TOC7" href="#SEC7">NEWLINES</a> 23<li><a name="TOC8" href="#SEC8">MULTITHREADING</a> 24<li><a name="TOC9" href="#SEC9">SAVING PRECOMPILED PATTERNS FOR LATER USE</a> 25<li><a name="TOC10" href="#SEC10">CHECKING BUILD-TIME OPTIONS</a> 26<li><a name="TOC11" href="#SEC11">COMPILING A PATTERN</a> 27<li><a name="TOC12" href="#SEC12">COMPILATION ERROR CODES</a> 28<li><a name="TOC13" href="#SEC13">STUDYING A PATTERN</a> 29<li><a name="TOC14" href="#SEC14">LOCALE SUPPORT</a> 30<li><a name="TOC15" href="#SEC15">INFORMATION ABOUT A PATTERN</a> 31<li><a name="TOC16" href="#SEC16">REFERENCE COUNTS</a> 32<li><a name="TOC17" href="#SEC17">MATCHING A PATTERN: THE TRADITIONAL FUNCTION</a> 33<li><a name="TOC18" href="#SEC18">EXTRACTING CAPTURED SUBSTRINGS BY NUMBER</a> 34<li><a name="TOC19" href="#SEC19">EXTRACTING CAPTURED SUBSTRINGS BY NAME</a> 35<li><a name="TOC20" href="#SEC20">DUPLICATE SUBPATTERN NAMES</a> 36<li><a name="TOC21" href="#SEC21">FINDING ALL POSSIBLE MATCHES</a> 37<li><a name="TOC22" href="#SEC22">OBTAINING AN ESTIMATE OF STACK USAGE</a> 38<li><a name="TOC23" href="#SEC23">MATCHING A PATTERN: THE ALTERNATIVE FUNCTION</a> 39<li><a name="TOC24" href="#SEC24">SEE ALSO</a> 40<li><a name="TOC25" href="#SEC25">AUTHOR</a> 41<li><a name="TOC26" href="#SEC26">REVISION</a> 42</ul> 43<P> 44<b>#include <pcre.h></b> 45</P> 46<br><a name="SEC1" href="#TOC1">PCRE NATIVE API BASIC FUNCTIONS</a><br> 47<P> 48<b>pcre *pcre_compile(const char *<i>pattern</i>, int <i>options</i>,</b> 49<b>const char **<i>errptr</i>, int *<i>erroffset</i>,</b> 50<b>const unsigned char *<i>tableptr</i>);</b> 51</P> 52<P> 53<b>pcre *pcre_compile2(const char *<i>pattern</i>, int <i>options</i>,</b> 54<b>int *<i>errorcodeptr</i>,</b> 55<b>const char **<i>errptr</i>, int *<i>erroffset</i>,</b> 56<b>const unsigned char *<i>tableptr</i>);</b> 57</P> 58<P> 59<b>pcre_extra *pcre_study(const pcre *<i>code</i>, int <i>options</i>,</b> 60<b>const char **<i>errptr</i>);</b> 61</P> 62<P> 63<b>void pcre_free_study(pcre_extra *<i>extra</i>);</b> 64</P> 65<P> 66<b>int pcre_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> 67<b>const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b> 68<b>int <i>options</i>, int *<i>ovector</i>, int <i>ovecsize</i>);</b> 69</P> 70<P> 71<b>int pcre_dfa_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> 72<b>const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b> 73<b>int <i>options</i>, int *<i>ovector</i>, int <i>ovecsize</i>,</b> 74<b>int *<i>workspace</i>, int <i>wscount</i>);</b> 75</P> 76<br><a name="SEC2" href="#TOC1">PCRE NATIVE API STRING EXTRACTION FUNCTIONS</a><br> 77<P> 78<b>int pcre_copy_named_substring(const pcre *<i>code</i>,</b> 79<b>const char *<i>subject</i>, int *<i>ovector</i>,</b> 80<b>int <i>stringcount</i>, const char *<i>stringname</i>,</b> 81<b>char *<i>buffer</i>, int <i>buffersize</i>);</b> 82</P> 83<P> 84<b>int pcre_copy_substring(const char *<i>subject</i>, int *<i>ovector</i>,</b> 85<b>int <i>stringcount</i>, int <i>stringnumber</i>, char *<i>buffer</i>,</b> 86<b>int <i>buffersize</i>);</b> 87</P> 88<P> 89<b>int pcre_get_named_substring(const pcre *<i>code</i>,</b> 90<b>const char *<i>subject</i>, int *<i>ovector</i>,</b> 91<b>int <i>stringcount</i>, const char *<i>stringname</i>,</b> 92<b>const char **<i>stringptr</i>);</b> 93</P> 94<P> 95<b>int pcre_get_stringnumber(const pcre *<i>code</i>,</b> 96<b>const char *<i>name</i>);</b> 97</P> 98<P> 99<b>int pcre_get_stringtable_entries(const pcre *<i>code</i>,</b> 100<b>const char *<i>name</i>, char **<i>first</i>, char **<i>last</i>);</b> 101</P> 102<P> 103<b>int pcre_get_substring(const char *<i>subject</i>, int *<i>ovector</i>,</b> 104<b>int <i>stringcount</i>, int <i>stringnumber</i>,</b> 105<b>const char **<i>stringptr</i>);</b> 106</P> 107<P> 108<b>int pcre_get_substring_list(const char *<i>subject</i>,</b> 109<b>int *<i>ovector</i>, int <i>stringcount</i>, const char ***<i>listptr</i>);</b> 110</P> 111<P> 112<b>void pcre_free_substring(const char *<i>stringptr</i>);</b> 113</P> 114<P> 115<b>void pcre_free_substring_list(const char **<i>stringptr</i>);</b> 116</P> 117<br><a name="SEC3" href="#TOC1">PCRE NATIVE API AUXILIARY FUNCTIONS</a><br> 118<P> 119<b>pcre_jit_stack *pcre_jit_stack_alloc(int <i>startsize</i>, int <i>maxsize</i>);</b> 120</P> 121<P> 122<b>void pcre_jit_stack_free(pcre_jit_stack *<i>stack</i>);</b> 123</P> 124<P> 125<b>void pcre_assign_jit_stack(pcre_extra *<i>extra</i>,</b> 126<b>pcre_jit_callback <i>callback</i>, void *<i>data</i>);</b> 127</P> 128<P> 129<b>const unsigned char *pcre_maketables(void);</b> 130</P> 131<P> 132<b>int pcre_fullinfo(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> 133<b>int <i>what</i>, void *<i>where</i>);</b> 134</P> 135<P> 136<b>int pcre_refcount(pcre *<i>code</i>, int <i>adjust</i>);</b> 137</P> 138<P> 139<b>int pcre_config(int <i>what</i>, void *<i>where</i>);</b> 140</P> 141<P> 142<b>const char *pcre_version(void);</b> 143</P> 144<P> 145<b>int pcre_pattern_to_host_byte_order(pcre *<i>code</i>,</b> 146<b>pcre_extra *<i>extra</i>, const unsigned char *<i>tables</i>);</b> 147</P> 148<br><a name="SEC4" href="#TOC1">PCRE NATIVE API INDIRECTED FUNCTIONS</a><br> 149<P> 150<b>void *(*pcre_malloc)(size_t);</b> 151</P> 152<P> 153<b>void (*pcre_free)(void *);</b> 154</P> 155<P> 156<b>void *(*pcre_stack_malloc)(size_t);</b> 157</P> 158<P> 159<b>void (*pcre_stack_free)(void *);</b> 160</P> 161<P> 162<b>int (*pcre_callout)(pcre_callout_block *);</b> 163</P> 164<br><a name="SEC5" href="#TOC1">PCRE 8-BIT AND 16-BIT LIBRARIES</a><br> 165<P> 166From release 8.30, PCRE can be compiled as a library for handling 16-bit 167character strings as well as, or instead of, the original library that handles 1688-bit character strings. To avoid too much complication, this document 169describes the 8-bit versions of the functions, with only occasional references 170to the 16-bit library. 171</P> 172<P> 173The 16-bit functions operate in the same way as their 8-bit counterparts; they 174just use different data types for their arguments and results, and their names 175start with <b>pcre16_</b> instead of <b>pcre_</b>. For every option that has UTF8 176in its name (for example, PCRE_UTF8), there is a corresponding 16-bit name with 177UTF8 replaced by UTF16. This facility is in fact just cosmetic; the 16-bit 178option names define the same bit values. 179</P> 180<P> 181References to bytes and UTF-8 in this document should be read as references to 18216-bit data quantities and UTF-16 when using the 16-bit library, unless 183specified otherwise. More details of the specific differences for the 16-bit 184library are given in the 185<a href="pcre16.html"><b>pcre16</b></a> 186page. 187</P> 188<br><a name="SEC6" href="#TOC1">PCRE API OVERVIEW</a><br> 189<P> 190PCRE has its own native API, which is described in this document. There are 191also some wrapper functions (for the 8-bit library only) that correspond to the 192POSIX regular expression API, but they do not give access to all the 193functionality. They are described in the 194<a href="pcreposix.html"><b>pcreposix</b></a> 195documentation. Both of these APIs define a set of C function calls. A C++ 196wrapper (again for the 8-bit library only) is also distributed with PCRE. It is 197documented in the 198<a href="pcrecpp.html"><b>pcrecpp</b></a> 199page. 200</P> 201<P> 202The native API C function prototypes are defined in the header file 203<b>pcre.h</b>, and on Unix-like systems the (8-bit) library itself is called 204<b>libpcre</b>. It can normally be accessed by adding <b>-lpcre</b> to the 205command for linking an application that uses PCRE. The header file defines the 206macros PCRE_MAJOR and PCRE_MINOR to contain the major and minor release numbers 207for the library. Applications can use these to include support for different 208releases of PCRE. 209</P> 210<P> 211In a Windows environment, if you want to statically link an application program 212against a non-dll <b>pcre.a</b> file, you must define PCRE_STATIC before 213including <b>pcre.h</b> or <b>pcrecpp.h</b>, because otherwise the 214<b>pcre_malloc()</b> and <b>pcre_free()</b> exported functions will be declared 215<b>__declspec(dllimport)</b>, with unwanted results. 216</P> 217<P> 218The functions <b>pcre_compile()</b>, <b>pcre_compile2()</b>, <b>pcre_study()</b>, 219and <b>pcre_exec()</b> are used for compiling and matching regular expressions 220in a Perl-compatible manner. A sample program that demonstrates the simplest 221way of using them is provided in the file called <i>pcredemo.c</i> in the PCRE 222source distribution. A listing of this program is given in the 223<a href="pcredemo.html"><b>pcredemo</b></a> 224documentation, and the 225<a href="pcresample.html"><b>pcresample</b></a> 226documentation describes how to compile and run it. 227</P> 228<P> 229Just-in-time compiler support is an optional feature of PCRE that can be built 230in appropriate hardware environments. It greatly speeds up the matching 231performance of many patterns. Simple programs can easily request that it be 232used if available, by setting an option that is ignored when it is not 233relevant. More complicated programs might need to make use of the functions 234<b>pcre_jit_stack_alloc()</b>, <b>pcre_jit_stack_free()</b>, and 235<b>pcre_assign_jit_stack()</b> in order to control the JIT code's memory usage. 236These functions are discussed in the 237<a href="pcrejit.html"><b>pcrejit</b></a> 238documentation. 239</P> 240<P> 241A second matching function, <b>pcre_dfa_exec()</b>, which is not 242Perl-compatible, is also provided. This uses a different algorithm for the 243matching. The alternative algorithm finds all possible matches (at a given 244point in the subject), and scans the subject just once (unless there are 245lookbehind assertions). However, this algorithm does not return captured 246substrings. A description of the two matching algorithms and their advantages 247and disadvantages is given in the 248<a href="pcrematching.html"><b>pcrematching</b></a> 249documentation. 250</P> 251<P> 252In addition to the main compiling and matching functions, there are convenience 253functions for extracting captured substrings from a subject string that is 254matched by <b>pcre_exec()</b>. They are: 255<pre> 256 <b>pcre_copy_substring()</b> 257 <b>pcre_copy_named_substring()</b> 258 <b>pcre_get_substring()</b> 259 <b>pcre_get_named_substring()</b> 260 <b>pcre_get_substring_list()</b> 261 <b>pcre_get_stringnumber()</b> 262 <b>pcre_get_stringtable_entries()</b> 263</pre> 264<b>pcre_free_substring()</b> and <b>pcre_free_substring_list()</b> are also 265provided, to free the memory used for extracted strings. 266</P> 267<P> 268The function <b>pcre_maketables()</b> is used to build a set of character tables 269in the current locale for passing to <b>pcre_compile()</b>, <b>pcre_exec()</b>, 270or <b>pcre_dfa_exec()</b>. This is an optional facility that is provided for 271specialist use. Most commonly, no special tables are passed, in which case 272internal tables that are generated when PCRE is built are used. 273</P> 274<P> 275The function <b>pcre_fullinfo()</b> is used to find out information about a 276compiled pattern. The function <b>pcre_version()</b> returns a pointer to a 277string containing the version of PCRE and its date of release. 278</P> 279<P> 280The function <b>pcre_refcount()</b> maintains a reference count in a data block 281containing a compiled pattern. This is provided for the benefit of 282object-oriented applications. 283</P> 284<P> 285The global variables <b>pcre_malloc</b> and <b>pcre_free</b> initially contain 286the entry points of the standard <b>malloc()</b> and <b>free()</b> functions, 287respectively. PCRE calls the memory management functions via these variables, 288so a calling program can replace them if it wishes to intercept the calls. This 289should be done before calling any PCRE functions. 290</P> 291<P> 292The global variables <b>pcre_stack_malloc</b> and <b>pcre_stack_free</b> are also 293indirections to memory management functions. These special functions are used 294only when PCRE is compiled to use the heap for remembering data, instead of 295recursive function calls, when running the <b>pcre_exec()</b> function. See the 296<a href="pcrebuild.html"><b>pcrebuild</b></a> 297documentation for details of how to do this. It is a non-standard way of 298building PCRE, for use in environments that have limited stacks. Because of the 299greater use of memory management, it runs more slowly. Separate functions are 300provided so that special-purpose external code can be used for this case. When 301used, these functions are always called in a stack-like manner (last obtained, 302first freed), and always for memory blocks of the same size. There is a 303discussion about PCRE's stack usage in the 304<a href="pcrestack.html"><b>pcrestack</b></a> 305documentation. 306</P> 307<P> 308The global variable <b>pcre_callout</b> initially contains NULL. It can be set 309by the caller to a "callout" function, which PCRE will then call at specified 310points during a matching operation. Details are given in the 311<a href="pcrecallout.html"><b>pcrecallout</b></a> 312documentation. 313<a name="newlines"></a></P> 314<br><a name="SEC7" href="#TOC1">NEWLINES</a><br> 315<P> 316PCRE supports five different conventions for indicating line breaks in 317strings: a single CR (carriage return) character, a single LF (linefeed) 318character, the two-character sequence CRLF, any of the three preceding, or any 319Unicode newline sequence. The Unicode newline sequences are the three just 320mentioned, plus the single characters VT (vertical tab, U+000B), FF (form feed, 321U+000C), NEL (next line, U+0085), LS (line separator, U+2028), and PS 322(paragraph separator, U+2029). 323</P> 324<P> 325Each of the first three conventions is used by at least one operating system as 326its standard newline sequence. When PCRE is built, a default can be specified. 327The default default is LF, which is the Unix standard. When PCRE is run, the 328default can be overridden, either when a pattern is compiled, or when it is 329matched. 330</P> 331<P> 332At compile time, the newline convention can be specified by the <i>options</i> 333argument of <b>pcre_compile()</b>, or it can be specified by special text at the 334start of the pattern itself; this overrides any other settings. See the 335<a href="pcrepattern.html"><b>pcrepattern</b></a> 336page for details of the special character sequences. 337</P> 338<P> 339In the PCRE documentation the word "newline" is used to mean "the character or 340pair of characters that indicate a line break". The choice of newline 341convention affects the handling of the dot, circumflex, and dollar 342metacharacters, the handling of #-comments in /x mode, and, when CRLF is a 343recognized line ending sequence, the match position advancement for a 344non-anchored pattern. There is more detail about this in the 345<a href="#execoptions">section on <b>pcre_exec()</b> options</a> 346below. 347</P> 348<P> 349The choice of newline convention does not affect the interpretation of 350the \n or \r escape sequences, nor does it affect what \R matches, which is 351controlled in a similar way, but by separate options. 352</P> 353<br><a name="SEC8" href="#TOC1">MULTITHREADING</a><br> 354<P> 355The PCRE functions can be used in multi-threading applications, with the 356proviso that the memory management functions pointed to by <b>pcre_malloc</b>, 357<b>pcre_free</b>, <b>pcre_stack_malloc</b>, and <b>pcre_stack_free</b>, and the 358callout function pointed to by <b>pcre_callout</b>, are shared by all threads. 359</P> 360<P> 361The compiled form of a regular expression is not altered during matching, so 362the same compiled pattern can safely be used by several threads at once. 363</P> 364<P> 365If the just-in-time optimization feature is being used, it needs separate 366memory stack areas for each thread. See the 367<a href="pcrejit.html"><b>pcrejit</b></a> 368documentation for more details. 369</P> 370<br><a name="SEC9" href="#TOC1">SAVING PRECOMPILED PATTERNS FOR LATER USE</a><br> 371<P> 372The compiled form of a regular expression can be saved and re-used at a later 373time, possibly by a different program, and even on a host other than the one on 374which it was compiled. Details are given in the 375<a href="pcreprecompile.html"><b>pcreprecompile</b></a> 376documentation, which includes a description of the 377<b>pcre_pattern_to_host_byte_order()</b> function. However, compiling a regular 378expression with one version of PCRE for use with a different version is not 379guaranteed to work and may cause crashes. 380</P> 381<br><a name="SEC10" href="#TOC1">CHECKING BUILD-TIME OPTIONS</a><br> 382<P> 383<b>int pcre_config(int <i>what</i>, void *<i>where</i>);</b> 384</P> 385<P> 386The function <b>pcre_config()</b> makes it possible for a PCRE client to 387discover which optional features have been compiled into the PCRE library. The 388<a href="pcrebuild.html"><b>pcrebuild</b></a> 389documentation has more details about these optional features. 390</P> 391<P> 392The first argument for <b>pcre_config()</b> is an integer, specifying which 393information is required; the second argument is a pointer to a variable into 394which the information is placed. The returned value is zero on success, or the 395negative error code PCRE_ERROR_BADOPTION if the value in the first argument is 396not recognized. The following information is available: 397<pre> 398 PCRE_CONFIG_UTF8 399</pre> 400The output is an integer that is set to one if UTF-8 support is available; 401otherwise it is set to zero. If this option is given to the 16-bit version of 402this function, <b>pcre16_config()</b>, the result is PCRE_ERROR_BADOPTION. 403<pre> 404 PCRE_CONFIG_UTF16 405</pre> 406The output is an integer that is set to one if UTF-16 support is available; 407otherwise it is set to zero. This value should normally be given to the 16-bit 408version of this function, <b>pcre16_config()</b>. If it is given to the 8-bit 409version of this function, the result is PCRE_ERROR_BADOPTION. 410<pre> 411 PCRE_CONFIG_UNICODE_PROPERTIES 412</pre> 413The output is an integer that is set to one if support for Unicode character 414properties is available; otherwise it is set to zero. 415<pre> 416 PCRE_CONFIG_JIT 417</pre> 418The output is an integer that is set to one if support for just-in-time 419compiling is available; otherwise it is set to zero. 420<pre> 421 PCRE_CONFIG_JITTARGET 422</pre> 423The output is a pointer to a zero-terminated "const char *" string. If JIT 424support is available, the string contains the name of the architecture for 425which the JIT compiler is configured, for example "x86 32bit (little endian + 426unaligned)". If JIT support is not available, the result is NULL. 427<pre> 428 PCRE_CONFIG_NEWLINE 429</pre> 430The output is an integer whose value specifies the default character sequence 431that is recognized as meaning "newline". The four values that are supported 432are: 10 for LF, 13 for CR, 3338 for CRLF, -2 for ANYCRLF, and -1 for ANY. 433Though they are derived from ASCII, the same values are returned in EBCDIC 434environments. The default should normally correspond to the standard sequence 435for your operating system. 436<pre> 437 PCRE_CONFIG_BSR 438</pre> 439The output is an integer whose value indicates what character sequences the \R 440escape sequence matches by default. A value of 0 means that \R matches any 441Unicode line ending sequence; a value of 1 means that \R matches only CR, LF, 442or CRLF. The default can be overridden when a pattern is compiled or matched. 443<pre> 444 PCRE_CONFIG_LINK_SIZE 445</pre> 446The output is an integer that contains the number of bytes used for internal 447linkage in compiled regular expressions. For the 8-bit library, the value can 448be 2, 3, or 4. For the 16-bit library, the value is either 2 or 4 and is still 449a number of bytes. The default value of 2 is sufficient for all but the most 450massive patterns, since it allows the compiled pattern to be up to 64K in size. 451Larger values allow larger regular expressions to be compiled, at the expense 452of slower matching. 453<pre> 454 PCRE_CONFIG_POSIX_MALLOC_THRESHOLD 455</pre> 456The output is an integer that contains the threshold above which the POSIX 457interface uses <b>malloc()</b> for output vectors. Further details are given in 458the 459<a href="pcreposix.html"><b>pcreposix</b></a> 460documentation. 461<pre> 462 PCRE_CONFIG_MATCH_LIMIT 463</pre> 464The output is a long integer that gives the default limit for the number of 465internal matching function calls in a <b>pcre_exec()</b> execution. Further 466details are given with <b>pcre_exec()</b> below. 467<pre> 468 PCRE_CONFIG_MATCH_LIMIT_RECURSION 469</pre> 470The output is a long integer that gives the default limit for the depth of 471recursion when calling the internal matching function in a <b>pcre_exec()</b> 472execution. Further details are given with <b>pcre_exec()</b> below. 473<pre> 474 PCRE_CONFIG_STACKRECURSE 475</pre> 476The output is an integer that is set to one if internal recursion when running 477<b>pcre_exec()</b> is implemented by recursive function calls that use the stack 478to remember their state. This is the usual way that PCRE is compiled. The 479output is zero if PCRE was compiled to use blocks of data on the heap instead 480of recursive function calls. In this case, <b>pcre_stack_malloc</b> and 481<b>pcre_stack_free</b> are called to manage memory blocks on the heap, thus 482avoiding the use of the stack. 483</P> 484<br><a name="SEC11" href="#TOC1">COMPILING A PATTERN</a><br> 485<P> 486<b>pcre *pcre_compile(const char *<i>pattern</i>, int <i>options</i>,</b> 487<b>const char **<i>errptr</i>, int *<i>erroffset</i>,</b> 488<b>const unsigned char *<i>tableptr</i>);</b> 489<b>pcre *pcre_compile2(const char *<i>pattern</i>, int <i>options</i>,</b> 490<b>int *<i>errorcodeptr</i>,</b> 491<b>const char **<i>errptr</i>, int *<i>erroffset</i>,</b> 492<b>const unsigned char *<i>tableptr</i>);</b> 493</P> 494<P> 495Either of the functions <b>pcre_compile()</b> or <b>pcre_compile2()</b> can be 496called to compile a pattern into an internal form. The only difference between 497the two interfaces is that <b>pcre_compile2()</b> has an additional argument, 498<i>errorcodeptr</i>, via which a numerical error code can be returned. To avoid 499too much repetition, we refer just to <b>pcre_compile()</b> below, but the 500information applies equally to <b>pcre_compile2()</b>. 501</P> 502<P> 503The pattern is a C string terminated by a binary zero, and is passed in the 504<i>pattern</i> argument. A pointer to a single block of memory that is obtained 505via <b>pcre_malloc</b> is returned. This contains the compiled code and related 506data. The <b>pcre</b> type is defined for the returned block; this is a typedef 507for a structure whose contents are not externally defined. It is up to the 508caller to free the memory (via <b>pcre_free</b>) when it is no longer required. 509</P> 510<P> 511Although the compiled code of a PCRE regex is relocatable, that is, it does not 512depend on memory location, the complete <b>pcre</b> data block is not 513fully relocatable, because it may contain a copy of the <i>tableptr</i> 514argument, which is an address (see below). 515</P> 516<P> 517The <i>options</i> argument contains various bit settings that affect the 518compilation. It should be zero if no options are required. The available 519options are described below. Some of them (in particular, those that are 520compatible with Perl, but some others as well) can also be set and unset from 521within the pattern (see the detailed description in the 522<a href="pcrepattern.html"><b>pcrepattern</b></a> 523documentation). For those options that can be different in different parts of 524the pattern, the contents of the <i>options</i> argument specifies their 525settings at the start of compilation and execution. The PCRE_ANCHORED, 526PCRE_BSR_<i>xxx</i>, PCRE_NEWLINE_<i>xxx</i>, PCRE_NO_UTF8_CHECK, and 527PCRE_NO_START_OPTIMIZE options can be set at the time of matching as well as at 528compile time. 529</P> 530<P> 531If <i>errptr</i> is NULL, <b>pcre_compile()</b> returns NULL immediately. 532Otherwise, if compilation of a pattern fails, <b>pcre_compile()</b> returns 533NULL, and sets the variable pointed to by <i>errptr</i> to point to a textual 534error message. This is a static string that is part of the library. You must 535not try to free it. Normally, the offset from the start of the pattern to the 536byte that was being processed when the error was discovered is placed in the 537variable pointed to by <i>erroffset</i>, which must not be NULL (if it is, an 538immediate error is given). However, for an invalid UTF-8 string, the offset is 539that of the first byte of the failing character. 540</P> 541<P> 542Some errors are not detected until the whole pattern has been scanned; in these 543cases, the offset passed back is the length of the pattern. Note that the 544offset is in bytes, not characters, even in UTF-8 mode. It may sometimes point 545into the middle of a UTF-8 character. 546</P> 547<P> 548If <b>pcre_compile2()</b> is used instead of <b>pcre_compile()</b>, and the 549<i>errorcodeptr</i> argument is not NULL, a non-zero error code number is 550returned via this argument in the event of an error. This is in addition to the 551textual error message. Error codes and messages are listed below. 552</P> 553<P> 554If the final argument, <i>tableptr</i>, is NULL, PCRE uses a default set of 555character tables that are built when PCRE is compiled, using the default C 556locale. Otherwise, <i>tableptr</i> must be an address that is the result of a 557call to <b>pcre_maketables()</b>. This value is stored with the compiled 558pattern, and used again by <b>pcre_exec()</b>, unless another table pointer is 559passed to it. For more discussion, see the section on locale support below. 560</P> 561<P> 562This code fragment shows a typical straightforward call to <b>pcre_compile()</b>: 563<pre> 564 pcre *re; 565 const char *error; 566 int erroffset; 567 re = pcre_compile( 568 "^A.*Z", /* the pattern */ 569 0, /* default options */ 570 &error, /* for error message */ 571 &erroffset, /* for error offset */ 572 NULL); /* use default character tables */ 573</pre> 574The following names for option bits are defined in the <b>pcre.h</b> header 575file: 576<pre> 577 PCRE_ANCHORED 578</pre> 579If this bit is set, the pattern is forced to be "anchored", that is, it is 580constrained to match only at the first matching point in the string that is 581being searched (the "subject string"). This effect can also be achieved by 582appropriate constructs in the pattern itself, which is the only way to do it in 583Perl. 584<pre> 585 PCRE_AUTO_CALLOUT 586</pre> 587If this bit is set, <b>pcre_compile()</b> automatically inserts callout items, 588all with number 255, before each pattern item. For discussion of the callout 589facility, see the 590<a href="pcrecallout.html"><b>pcrecallout</b></a> 591documentation. 592<pre> 593 PCRE_BSR_ANYCRLF 594 PCRE_BSR_UNICODE 595</pre> 596These options (which are mutually exclusive) control what the \R escape 597sequence matches. The choice is either to match only CR, LF, or CRLF, or to 598match any Unicode newline sequence. The default is specified when PCRE is 599built. It can be overridden from within the pattern, or by setting an option 600when a compiled pattern is matched. 601<pre> 602 PCRE_CASELESS 603</pre> 604If this bit is set, letters in the pattern match both upper and lower case 605letters. It is equivalent to Perl's /i option, and it can be changed within a 606pattern by a (?i) option setting. In UTF-8 mode, PCRE always understands the 607concept of case for characters whose values are less than 128, so caseless 608matching is always possible. For characters with higher values, the concept of 609case is supported if PCRE is compiled with Unicode property support, but not 610otherwise. If you want to use caseless matching for characters 128 and above, 611you must ensure that PCRE is compiled with Unicode property support as well as 612with UTF-8 support. 613<pre> 614 PCRE_DOLLAR_ENDONLY 615</pre> 616If this bit is set, a dollar metacharacter in the pattern matches only at the 617end of the subject string. Without this option, a dollar also matches 618immediately before a newline at the end of the string (but not before any other 619newlines). The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is set. 620There is no equivalent to this option in Perl, and no way to set it within a 621pattern. 622<pre> 623 PCRE_DOTALL 624</pre> 625If this bit is set, a dot metacharacter in the pattern matches a character of 626any value, including one that indicates a newline. However, it only ever 627matches one character, even if newlines are coded as CRLF. Without this option, 628a dot does not match when the current position is at a newline. This option is 629equivalent to Perl's /s option, and it can be changed within a pattern by a 630(?s) option setting. A negative class such as [^a] always matches newline 631characters, independent of the setting of this option. 632<pre> 633 PCRE_DUPNAMES 634</pre> 635If this bit is set, names used to identify capturing subpatterns need not be 636unique. This can be helpful for certain types of pattern when it is known that 637only one instance of the named subpattern can ever be matched. There are more 638details of named subpatterns below; see also the 639<a href="pcrepattern.html"><b>pcrepattern</b></a> 640documentation. 641<pre> 642 PCRE_EXTENDED 643</pre> 644If this bit is set, white space data characters in the pattern are totally 645ignored except when escaped or inside a character class. White space does not 646include the VT character (code 11). In addition, characters between an 647unescaped # outside a character class and the next newline, inclusive, are also 648ignored. This is equivalent to Perl's /x option, and it can be changed within a 649pattern by a (?x) option setting. 650</P> 651<P> 652Which characters are interpreted as newlines is controlled by the options 653passed to <b>pcre_compile()</b> or by a special sequence at the start of the 654pattern, as described in the section entitled 655<a href="pcrepattern.html#newlines">"Newline conventions"</a> 656in the <b>pcrepattern</b> documentation. Note that the end of this type of 657comment is a literal newline sequence in the pattern; escape sequences that 658happen to represent a newline do not count. 659</P> 660<P> 661This option makes it possible to include comments inside complicated patterns. 662Note, however, that this applies only to data characters. White space characters 663may never appear within special character sequences in a pattern, for example 664within the sequence (?( that introduces a conditional subpattern. 665<pre> 666 PCRE_EXTRA 667</pre> 668This option was invented in order to turn on additional functionality of PCRE 669that is incompatible with Perl, but it is currently of very little use. When 670set, any backslash in a pattern that is followed by a letter that has no 671special meaning causes an error, thus reserving these combinations for future 672expansion. By default, as in Perl, a backslash followed by a letter with no 673special meaning is treated as a literal. (Perl can, however, be persuaded to 674give an error for this, by running it with the -w option.) There are at present 675no other features controlled by this option. It can also be set by a (?X) 676option setting within a pattern. 677<pre> 678 PCRE_FIRSTLINE 679</pre> 680If this option is set, an unanchored pattern is required to match before or at 681the first newline in the subject string, though the matched text may continue 682over the newline. 683<pre> 684 PCRE_JAVASCRIPT_COMPAT 685</pre> 686If this option is set, PCRE's behaviour is changed in some ways so that it is 687compatible with JavaScript rather than Perl. The changes are as follows: 688</P> 689<P> 690(1) A lone closing square bracket in a pattern causes a compile-time error, 691because this is illegal in JavaScript (by default it is treated as a data 692character). Thus, the pattern AB]CD becomes illegal when this option is set. 693</P> 694<P> 695(2) At run time, a back reference to an unset subpattern group matches an empty 696string (by default this causes the current matching alternative to fail). A 697pattern such as (\1)(a) succeeds when this option is set (assuming it can find 698an "a" in the subject), whereas it fails by default, for Perl compatibility. 699</P> 700<P> 701(3) \U matches an upper case "U" character; by default \U causes a compile 702time error (Perl uses \U to upper case subsequent characters). 703</P> 704<P> 705(4) \u matches a lower case "u" character unless it is followed by four 706hexadecimal digits, in which case the hexadecimal number defines the code point 707to match. By default, \u causes a compile time error (Perl uses it to upper 708case the following character). 709</P> 710<P> 711(5) \x matches a lower case "x" character unless it is followed by two 712hexadecimal digits, in which case the hexadecimal number defines the code point 713to match. By default, as in Perl, a hexadecimal number is always expected after 714\x, but it may have zero, one, or two digits (so, for example, \xz matches a 715binary zero character followed by z). 716<pre> 717 PCRE_MULTILINE 718</pre> 719By default, PCRE treats the subject string as consisting of a single line of 720characters (even if it actually contains newlines). The "start of line" 721metacharacter (^) matches only at the start of the string, while the "end of 722line" metacharacter ($) matches only at the end of the string, or before a 723terminating newline (unless PCRE_DOLLAR_ENDONLY is set). This is the same as 724Perl. 725</P> 726<P> 727When PCRE_MULTILINE it is set, the "start of line" and "end of line" constructs 728match immediately following or immediately before internal newlines in the 729subject string, respectively, as well as at the very start and end. This is 730equivalent to Perl's /m option, and it can be changed within a pattern by a 731(?m) option setting. If there are no newlines in a subject string, or no 732occurrences of ^ or $ in a pattern, setting PCRE_MULTILINE has no effect. 733<pre> 734 PCRE_NEWLINE_CR 735 PCRE_NEWLINE_LF 736 PCRE_NEWLINE_CRLF 737 PCRE_NEWLINE_ANYCRLF 738 PCRE_NEWLINE_ANY 739</pre> 740These options override the default newline definition that was chosen when PCRE 741was built. Setting the first or the second specifies that a newline is 742indicated by a single character (CR or LF, respectively). Setting 743PCRE_NEWLINE_CRLF specifies that a newline is indicated by the two-character 744CRLF sequence. Setting PCRE_NEWLINE_ANYCRLF specifies that any of the three 745preceding sequences should be recognized. Setting PCRE_NEWLINE_ANY specifies 746that any Unicode newline sequence should be recognized. The Unicode newline 747sequences are the three just mentioned, plus the single characters VT (vertical 748tab, U+000B), FF (form feed, U+000C), NEL (next line, U+0085), LS (line 749separator, U+2028), and PS (paragraph separator, U+2029). For the 8-bit 750library, the last two are recognized only in UTF-8 mode. 751</P> 752<P> 753The newline setting in the options word uses three bits that are treated 754as a number, giving eight possibilities. Currently only six are used (default 755plus the five values above). This means that if you set more than one newline 756option, the combination may or may not be sensible. For example, 757PCRE_NEWLINE_CR with PCRE_NEWLINE_LF is equivalent to PCRE_NEWLINE_CRLF, but 758other combinations may yield unused numbers and cause an error. 759</P> 760<P> 761The only time that a line break in a pattern is specially recognized when 762compiling is when PCRE_EXTENDED is set. CR and LF are white space characters, 763and so are ignored in this mode. Also, an unescaped # outside a character class 764indicates a comment that lasts until after the next line break sequence. In 765other circumstances, line break sequences in patterns are treated as literal 766data. 767</P> 768<P> 769The newline option that is set at compile time becomes the default that is used 770for <b>pcre_exec()</b> and <b>pcre_dfa_exec()</b>, but it can be overridden. 771<pre> 772 PCRE_NO_AUTO_CAPTURE 773</pre> 774If this option is set, it disables the use of numbered capturing parentheses in 775the pattern. Any opening parenthesis that is not followed by ? behaves as if it 776were followed by ?: but named parentheses can still be used for capturing (and 777they acquire numbers in the usual way). There is no equivalent of this option 778in Perl. 779<pre> 780 NO_START_OPTIMIZE 781</pre> 782This is an option that acts at matching time; that is, it is really an option 783for <b>pcre_exec()</b> or <b>pcre_dfa_exec()</b>. If it is set at compile time, 784it is remembered with the compiled pattern and assumed at matching time. For 785details see the discussion of PCRE_NO_START_OPTIMIZE 786<a href="#execoptions">below.</a> 787<pre> 788 PCRE_UCP 789</pre> 790This option changes the way PCRE processes \B, \b, \D, \d, \S, \s, \W, 791\w, and some of the POSIX character classes. By default, only ASCII characters 792are recognized, but if PCRE_UCP is set, Unicode properties are used instead to 793classify characters. More details are given in the section on 794<a href="pcre.html#genericchartypes">generic character types</a> 795in the 796<a href="pcrepattern.html"><b>pcrepattern</b></a> 797page. If you set PCRE_UCP, matching one of the items it affects takes much 798longer. The option is available only if PCRE has been compiled with Unicode 799property support. 800<pre> 801 PCRE_UNGREEDY 802</pre> 803This option inverts the "greediness" of the quantifiers so that they are not 804greedy by default, but become greedy if followed by "?". It is not compatible 805with Perl. It can also be set by a (?U) option setting within the pattern. 806<pre> 807 PCRE_UTF8 808</pre> 809This option causes PCRE to regard both the pattern and the subject as strings 810of UTF-8 characters instead of single-byte strings. However, it is available 811only when PCRE is built to include UTF support. If not, the use of this option 812provokes an error. Details of how this option changes the behaviour of PCRE are 813given in the 814<a href="pcreunicode.html"><b>pcreunicode</b></a> 815page. 816<pre> 817 PCRE_NO_UTF8_CHECK 818</pre> 819When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 820string is automatically checked. There is a discussion about the 821<a href="pcreunicode.html#utf8strings">validity of UTF-8 strings</a> 822in the 823<a href="pcreunicode.html"><b>pcreunicode</b></a> 824page. If an invalid UTF-8 sequence is found, <b>pcre_compile()</b> returns an 825error. If you already know that your pattern is valid, and you want to skip 826this check for performance reasons, you can set the PCRE_NO_UTF8_CHECK option. 827When it is set, the effect of passing an invalid UTF-8 string as a pattern is 828undefined. It may cause your program to crash. Note that this option can also 829be passed to <b>pcre_exec()</b> and <b>pcre_dfa_exec()</b>, to suppress the 830validity checking of subject strings. 831</P> 832<br><a name="SEC12" href="#TOC1">COMPILATION ERROR CODES</a><br> 833<P> 834The following table lists the error codes than may be returned by 835<b>pcre_compile2()</b>, along with the error messages that may be returned by 836both compiling functions. Note that error messages are always 8-bit ASCII 837strings, even in 16-bit mode. As PCRE has developed, some error codes have 838fallen out of use. To avoid confusion, they have not been re-used. 839<pre> 840 0 no error 841 1 \ at end of pattern 842 2 \c at end of pattern 843 3 unrecognized character follows \ 844 4 numbers out of order in {} quantifier 845 5 number too big in {} quantifier 846 6 missing terminating ] for character class 847 7 invalid escape sequence in character class 848 8 range out of order in character class 849 9 nothing to repeat 850 10 [this code is not in use] 851 11 internal error: unexpected repeat 852 12 unrecognized character after (? or (?- 853 13 POSIX named classes are supported only within a class 854 14 missing ) 855 15 reference to non-existent subpattern 856 16 erroffset passed as NULL 857 17 unknown option bit(s) set 858 18 missing ) after comment 859 19 [this code is not in use] 860 20 regular expression is too large 861 21 failed to get memory 862 22 unmatched parentheses 863 23 internal error: code overflow 864 24 unrecognized character after (?< 865 25 lookbehind assertion is not fixed length 866 26 malformed number or name after (?( 867 27 conditional group contains more than two branches 868 28 assertion expected after (?( 869 29 (?R or (?[+-]digits must be followed by ) 870 30 unknown POSIX class name 871 31 POSIX collating elements are not supported 872 32 this version of PCRE is compiled without UTF support 873 33 [this code is not in use] 874 34 character value in \x{...} sequence is too large 875 35 invalid condition (?(0) 876 36 \C not allowed in lookbehind assertion 877 37 PCRE does not support \L, \l, \N{name}, \U, or \u 878 38 number after (?C is > 255 879 39 closing ) for (?C expected 880 40 recursive call could loop indefinitely 881 41 unrecognized character after (?P 882 42 syntax error in subpattern name (missing terminator) 883 43 two named subpatterns have the same name 884 44 invalid UTF-8 string (specifically UTF-8) 885 45 support for \P, \p, and \X has not been compiled 886 46 malformed \P or \p sequence 887 47 unknown property name after \P or \p 888 48 subpattern name is too long (maximum 32 characters) 889 49 too many named subpatterns (maximum 10000) 890 50 [this code is not in use] 891 51 octal value is greater than \377 in 8-bit non-UTF-8 mode 892 52 internal error: overran compiling workspace 893 53 internal error: previously-checked referenced subpattern 894 not found 895 54 DEFINE group contains more than one branch 896 55 repeating a DEFINE group is not allowed 897 56 inconsistent NEWLINE options 898 57 \g is not followed by a braced, angle-bracketed, or quoted 899 name/number or by a plain number 900 58 a numbered reference must not be zero 901 59 an argument is not allowed for (*ACCEPT), (*FAIL), or (*COMMIT) 902 60 (*VERB) not recognized 903 61 number is too big 904 62 subpattern name expected 905 63 digit expected after (?+ 906 64 ] is an invalid data character in JavaScript compatibility mode 907 65 different names for subpatterns of the same number are 908 not allowed 909 66 (*MARK) must have an argument 910 67 this version of PCRE is not compiled with Unicode property 911 support 912 68 \c must be followed by an ASCII character 913 69 \k is not followed by a braced, angle-bracketed, or quoted name 914 70 internal error: unknown opcode in find_fixedlength() 915 71 \N is not supported in a class 916 72 too many forward references 917 73 disallowed Unicode code point (>= 0xd800 && <= 0xdfff) 918 74 invalid UTF-16 string (specifically UTF-16) 919 75 name is too long in (*MARK), (*PRUNE), (*SKIP), or (*THEN) 920 76 character value in \u.... sequence is too large 921</pre> 922The numbers 32 and 10000 in errors 48 and 49 are defaults; different values may 923be used if the limits were changed when PCRE was built. 924<a name="studyingapattern"></a></P> 925<br><a name="SEC13" href="#TOC1">STUDYING A PATTERN</a><br> 926<P> 927<b>pcre_extra *pcre_study(const pcre *<i>code</i>, int <i>options</i></b> 928<b>const char **<i>errptr</i>);</b> 929</P> 930<P> 931If a compiled pattern is going to be used several times, it is worth spending 932more time analyzing it in order to speed up the time taken for matching. The 933function <b>pcre_study()</b> takes a pointer to a compiled pattern as its first 934argument. If studying the pattern produces additional information that will 935help speed up matching, <b>pcre_study()</b> returns a pointer to a 936<b>pcre_extra</b> block, in which the <i>study_data</i> field points to the 937results of the study. 938</P> 939<P> 940The returned value from <b>pcre_study()</b> can be passed directly to 941<b>pcre_exec()</b> or <b>pcre_dfa_exec()</b>. However, a <b>pcre_extra</b> block 942also contains other fields that can be set by the caller before the block is 943passed; these are described 944<a href="#extradata">below</a> 945in the section on matching a pattern. 946</P> 947<P> 948If studying the pattern does not produce any useful information, 949<b>pcre_study()</b> returns NULL. In that circumstance, if the calling program 950wants to pass any of the other fields to <b>pcre_exec()</b> or 951<b>pcre_dfa_exec()</b>, it must set up its own <b>pcre_extra</b> block. 952</P> 953<P> 954The second argument of <b>pcre_study()</b> contains option bits. There are three 955options: 956<pre> 957 PCRE_STUDY_JIT_COMPILE 958 PCRE_STUDY_JIT_PARTIAL_HARD_COMPILE 959 PCRE_STUDY_JIT_PARTIAL_SOFT_COMPILE 960</pre> 961If any of these are set, and the just-in-time compiler is available, the 962pattern is further compiled into machine code that executes much faster than 963the <b>pcre_exec()</b> interpretive matching function. If the just-in-time 964compiler is not available, these options are ignored. All other bits in the 965<i>options</i> argument must be zero. 966</P> 967<P> 968JIT compilation is a heavyweight optimization. It can take some time for 969patterns to be analyzed, and for one-off matches and simple patterns the 970benefit of faster execution might be offset by a much slower study time. 971Not all patterns can be optimized by the JIT compiler. For those that cannot be 972handled, matching automatically falls back to the <b>pcre_exec()</b> 973interpreter. For more details, see the 974<a href="pcrejit.html"><b>pcrejit</b></a> 975documentation. 976</P> 977<P> 978The third argument for <b>pcre_study()</b> is a pointer for an error message. If 979studying succeeds (even if no data is returned), the variable it points to is 980set to NULL. Otherwise it is set to point to a textual error message. This is a 981static string that is part of the library. You must not try to free it. You 982should test the error pointer for NULL after calling <b>pcre_study()</b>, to be 983sure that it has run successfully. 984</P> 985<P> 986When you are finished with a pattern, you can free the memory used for the 987study data by calling <b>pcre_free_study()</b>. This function was added to the 988API for release 8.20. For earlier versions, the memory could be freed with 989<b>pcre_free()</b>, just like the pattern itself. This will still work in cases 990where JIT optimization is not used, but it is advisable to change to the new 991function when convenient. 992</P> 993<P> 994This is a typical way in which <b>pcre_study</b>() is used (except that in a 995real application there should be tests for errors): 996<pre> 997 int rc; 998 pcre *re; 999 pcre_extra *sd; 1000 re = pcre_compile("pattern", 0, &error, &erroroffset, NULL); 1001 sd = pcre_study( 1002 re, /* result of pcre_compile() */ 1003 0, /* no options */ 1004 &error); /* set to NULL or points to a message */ 1005 rc = pcre_exec( /* see below for details of pcre_exec() options */ 1006 re, sd, "subject", 7, 0, 0, ovector, 30); 1007 ... 1008 pcre_free_study(sd); 1009 pcre_free(re); 1010</pre> 1011Studying a pattern does two things: first, a lower bound for the length of 1012subject string that is needed to match the pattern is computed. This does not 1013mean that there are any strings of that length that match, but it does 1014guarantee that no shorter strings match. The value is used by 1015<b>pcre_exec()</b> and <b>pcre_dfa_exec()</b> to avoid wasting time by trying to 1016match strings that are shorter than the lower bound. You can find out the value 1017in a calling program via the <b>pcre_fullinfo()</b> function. 1018</P> 1019<P> 1020Studying a pattern is also useful for non-anchored patterns that do not have a 1021single fixed starting character. A bitmap of possible starting bytes is 1022created. This speeds up finding a position in the subject at which to start 1023matching. (In 16-bit mode, the bitmap is used for 16-bit values less than 256.) 1024</P> 1025<P> 1026These two optimizations apply to both <b>pcre_exec()</b> and 1027<b>pcre_dfa_exec()</b>, and the information is also used by the JIT compiler. 1028The optimizations can be disabled by setting the PCRE_NO_START_OPTIMIZE option 1029when calling <b>pcre_exec()</b> or <b>pcre_dfa_exec()</b>, but if this is done, 1030JIT execution is also disabled. You might want to do this if your pattern 1031contains callouts or (*MARK) and you want to make use of these facilities in 1032cases where matching fails. See the discussion of PCRE_NO_START_OPTIMIZE 1033<a href="#execoptions">below.</a> 1034<a name="localesupport"></a></P> 1035<br><a name="SEC14" href="#TOC1">LOCALE SUPPORT</a><br> 1036<P> 1037PCRE handles caseless matching, and determines whether characters are letters, 1038digits, or whatever, by reference to a set of tables, indexed by character 1039value. When running in UTF-8 mode, this applies only to characters 1040with codes less than 128. By default, higher-valued codes never match escapes 1041such as \w or \d, but they can be tested with \p if PCRE is built with 1042Unicode character property support. Alternatively, the PCRE_UCP option can be 1043set at compile time; this causes \w and friends to use Unicode property 1044support instead of built-in tables. The use of locales with Unicode is 1045discouraged. If you are handling characters with codes greater than 128, you 1046should either use UTF-8 and Unicode, or use locales, but not try to mix the 1047two. 1048</P> 1049<P> 1050PCRE contains an internal set of tables that are used when the final argument 1051of <b>pcre_compile()</b> is NULL. These are sufficient for many applications. 1052Normally, the internal tables recognize only ASCII characters. However, when 1053PCRE is built, it is possible to cause the internal tables to be rebuilt in the 1054default "C" locale of the local system, which may cause them to be different. 1055</P> 1056<P> 1057The internal tables can always be overridden by tables supplied by the 1058application that calls PCRE. These may be created in a different locale from 1059the default. As more and more applications change to using Unicode, the need 1060for this locale support is expected to die away. 1061</P> 1062<P> 1063External tables are built by calling the <b>pcre_maketables()</b> function, 1064which has no arguments, in the relevant locale. The result can then be passed 1065to <b>pcre_compile()</b> or <b>pcre_exec()</b> as often as necessary. For 1066example, to build and use tables that are appropriate for the French locale 1067(where accented characters with values greater than 128 are treated as letters), 1068the following code could be used: 1069<pre> 1070 setlocale(LC_CTYPE, "fr_FR"); 1071 tables = pcre_maketables(); 1072 re = pcre_compile(..., tables); 1073</pre> 1074The locale name "fr_FR" is used on Linux and other Unix-like systems; if you 1075are using Windows, the name for the French locale is "french". 1076</P> 1077<P> 1078When <b>pcre_maketables()</b> runs, the tables are built in memory that is 1079obtained via <b>pcre_malloc</b>. It is the caller's responsibility to ensure 1080that the memory containing the tables remains available for as long as it is 1081needed. 1082</P> 1083<P> 1084The pointer that is passed to <b>pcre_compile()</b> is saved with the compiled 1085pattern, and the same tables are used via this pointer by <b>pcre_study()</b> 1086and normally also by <b>pcre_exec()</b>. Thus, by default, for any single 1087pattern, compilation, studying and matching all happen in the same locale, but 1088different patterns can be compiled in different locales. 1089</P> 1090<P> 1091It is possible to pass a table pointer or NULL (indicating the use of the 1092internal tables) to <b>pcre_exec()</b>. Although not intended for this purpose, 1093this facility could be used to match a pattern in a different locale from the 1094one in which it was compiled. Passing table pointers at run time is discussed 1095below in the section on matching a pattern. 1096<a name="infoaboutpattern"></a></P> 1097<br><a name="SEC15" href="#TOC1">INFORMATION ABOUT A PATTERN</a><br> 1098<P> 1099<b>int pcre_fullinfo(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> 1100<b>int <i>what</i>, void *<i>where</i>);</b> 1101</P> 1102<P> 1103The <b>pcre_fullinfo()</b> function returns information about a compiled 1104pattern. It replaces the <b>pcre_info()</b> function, which was removed from the 1105library at version 8.30, after more than 10 years of obsolescence. 1106</P> 1107<P> 1108The first argument for <b>pcre_fullinfo()</b> is a pointer to the compiled 1109pattern. The second argument is the result of <b>pcre_study()</b>, or NULL if 1110the pattern was not studied. The third argument specifies which piece of 1111information is required, and the fourth argument is a pointer to a variable 1112to receive the data. The yield of the function is zero for success, or one of 1113the following negative numbers: 1114<pre> 1115 PCRE_ERROR_NULL the argument <i>code</i> was NULL 1116 the argument <i>where</i> was NULL 1117 PCRE_ERROR_BADMAGIC the "magic number" was not found 1118 PCRE_ERROR_BADENDIANNESS the pattern was compiled with different 1119 endianness 1120 PCRE_ERROR_BADOPTION the value of <i>what</i> was invalid 1121</pre> 1122The "magic number" is placed at the start of each compiled pattern as an simple 1123check against passing an arbitrary memory pointer. The endianness error can 1124occur if a compiled pattern is saved and reloaded on a different host. Here is 1125a typical call of <b>pcre_fullinfo()</b>, to obtain the length of the compiled 1126pattern: 1127<pre> 1128 int rc; 1129 size_t length; 1130 rc = pcre_fullinfo( 1131 re, /* result of pcre_compile() */ 1132 sd, /* result of pcre_study(), or NULL */ 1133 PCRE_INFO_SIZE, /* what is required */ 1134 &length); /* where to put the data */ 1135</pre> 1136The possible values for the third argument are defined in <b>pcre.h</b>, and are 1137as follows: 1138<pre> 1139 PCRE_INFO_BACKREFMAX 1140</pre> 1141Return the number of the highest back reference in the pattern. The fourth 1142argument should point to an <b>int</b> variable. Zero is returned if there are 1143no back references. 1144<pre> 1145 PCRE_INFO_CAPTURECOUNT 1146</pre> 1147Return the number of capturing subpatterns in the pattern. The fourth argument 1148should point to an <b>int</b> variable. 1149<pre> 1150 PCRE_INFO_DEFAULT_TABLES 1151</pre> 1152Return a pointer to the internal default character tables within PCRE. The 1153fourth argument should point to an <b>unsigned char *</b> variable. This 1154information call is provided for internal use by the <b>pcre_study()</b> 1155function. External callers can cause PCRE to use its internal tables by passing 1156a NULL table pointer. 1157<pre> 1158 PCRE_INFO_FIRSTBYTE 1159</pre> 1160Return information about the first data unit of any matched string, for a 1161non-anchored pattern. (The name of this option refers to the 8-bit library, 1162where data units are bytes.) The fourth argument should point to an <b>int</b> 1163variable. 1164</P> 1165<P> 1166If there is a fixed first value, for example, the letter "c" from a pattern 1167such as (cat|cow|coyote), its value is returned. In the 8-bit library, the 1168value is always less than 256; in the 16-bit library the value can be up to 11690xffff. 1170</P> 1171<P> 1172If there is no fixed first value, and if either 1173<br> 1174<br> 1175(a) the pattern was compiled with the PCRE_MULTILINE option, and every branch 1176starts with "^", or 1177<br> 1178<br> 1179(b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not set 1180(if it were set, the pattern would be anchored), 1181<br> 1182<br> 1183-1 is returned, indicating that the pattern matches only at the start of a 1184subject string or after any newline within the string. Otherwise -2 is 1185returned. For anchored patterns, -2 is returned. 1186<pre> 1187 PCRE_INFO_FIRSTTABLE 1188</pre> 1189If the pattern was studied, and this resulted in the construction of a 256-bit 1190table indicating a fixed set of values for the first data unit in any matching 1191string, a pointer to the table is returned. Otherwise NULL is returned. The 1192fourth argument should point to an <b>unsigned char *</b> variable. 1193<pre> 1194 PCRE_INFO_HASCRORLF 1195</pre> 1196Return 1 if the pattern contains any explicit matches for CR or LF characters, 1197otherwise 0. The fourth argument should point to an <b>int</b> variable. An 1198explicit match is either a literal CR or LF character, or \r or \n. 1199<pre> 1200 PCRE_INFO_JCHANGED 1201</pre> 1202Return 1 if the (?J) or (?-J) option setting is used in the pattern, otherwise 12030. The fourth argument should point to an <b>int</b> variable. (?J) and 1204(?-J) set and unset the local PCRE_DUPNAMES option, respectively. 1205<pre> 1206 PCRE_INFO_JIT 1207</pre> 1208Return 1 if the pattern was studied with one of the JIT options, and 1209just-in-time compiling was successful. The fourth argument should point to an 1210<b>int</b> variable. A return value of 0 means that JIT support is not available 1211in this version of PCRE, or that the pattern was not studied with a JIT option, 1212or that the JIT compiler could not handle this particular pattern. See the 1213<a href="pcrejit.html"><b>pcrejit</b></a> 1214documentation for details of what can and cannot be handled. 1215<pre> 1216 PCRE_INFO_JITSIZE 1217</pre> 1218If the pattern was successfully studied with a JIT option, return the size of 1219the JIT compiled code, otherwise return zero. The fourth argument should point 1220to a <b>size_t</b> variable. 1221<pre> 1222 PCRE_INFO_LASTLITERAL 1223</pre> 1224Return the value of the rightmost literal data unit that must exist in any 1225matched string, other than at its start, if such a value has been recorded. The 1226fourth argument should point to an <b>int</b> variable. If there is no such 1227value, -1 is returned. For anchored patterns, a last literal value is recorded 1228only if it follows something of variable length. For example, for the pattern 1229/^a\d+z\d+/ the returned value is "z", but for /^a\dz\d/ the returned value 1230is -1. 1231<pre> 1232 PCRE_INFO_MAXLOOKBEHIND 1233</pre> 1234Return the number of characters (NB not bytes) in the longest lookbehind 1235assertion in the pattern. Note that the simple assertions \b and \B require a 1236one-character lookbehind. This information is useful when doing multi-segment 1237matching using the partial matching facilities. 1238<pre> 1239 PCRE_INFO_MINLENGTH 1240</pre> 1241If the pattern was studied and a minimum length for matching subject strings 1242was computed, its value is returned. Otherwise the returned value is -1. The 1243value is a number of characters, which in UTF-8 mode may be different from the 1244number of bytes. The fourth argument should point to an <b>int</b> variable. A 1245non-negative value is a lower bound to the length of any matching string. There 1246may not be any strings of that length that do actually match, but every string 1247that does match is at least that long. 1248<pre> 1249 PCRE_INFO_NAMECOUNT 1250 PCRE_INFO_NAMEENTRYSIZE 1251 PCRE_INFO_NAMETABLE 1252</pre> 1253PCRE supports the use of named as well as numbered capturing parentheses. The 1254names are just an additional way of identifying the parentheses, which still 1255acquire numbers. Several convenience functions such as 1256<b>pcre_get_named_substring()</b> are provided for extracting captured 1257substrings by name. It is also possible to extract the data directly, by first 1258converting the name to a number in order to access the correct pointers in the 1259output vector (described with <b>pcre_exec()</b> below). To do the conversion, 1260you need to use the name-to-number map, which is described by these three 1261values. 1262</P> 1263<P> 1264The map consists of a number of fixed-size entries. PCRE_INFO_NAMECOUNT gives 1265the number of entries, and PCRE_INFO_NAMEENTRYSIZE gives the size of each 1266entry; both of these return an <b>int</b> value. The entry size depends on the 1267length of the longest name. PCRE_INFO_NAMETABLE returns a pointer to the first 1268entry of the table. This is a pointer to <b>char</b> in the 8-bit library, where 1269the first two bytes of each entry are the number of the capturing parenthesis, 1270most significant byte first. In the 16-bit library, the pointer points to 127116-bit data units, the first of which contains the parenthesis number. The rest 1272of the entry is the corresponding name, zero terminated. 1273</P> 1274<P> 1275The names are in alphabetical order. Duplicate names may appear if (?| is used 1276to create multiple groups with the same number, as described in the 1277<a href="pcrepattern.html#dupsubpatternnumber">section on duplicate subpattern numbers</a> 1278in the 1279<a href="pcrepattern.html"><b>pcrepattern</b></a> 1280page. Duplicate names for subpatterns with different numbers are permitted only 1281if PCRE_DUPNAMES is set. In all cases of duplicate names, they appear in the 1282table in the order in which they were found in the pattern. In the absence of 1283(?| this is the order of increasing number; when (?| is used this is not 1284necessarily the case because later subpatterns may have lower numbers. 1285</P> 1286<P> 1287As a simple example of the name/number table, consider the following pattern 1288after compilation by the 8-bit library (assume PCRE_EXTENDED is set, so white 1289space - including newlines - is ignored): 1290<pre> 1291 (?<date> (?<year>(\d\d)?\d\d) - (?<month>\d\d) - (?<day>\d\d) ) 1292</pre> 1293There are four named subpatterns, so the table has four entries, and each entry 1294in the table is eight bytes long. The table is as follows, with non-printing 1295bytes shows in hexadecimal, and undefined bytes shown as ??: 1296<pre> 1297 00 01 d a t e 00 ?? 1298 00 05 d a y 00 ?? ?? 1299 00 04 m o n t h 00 1300 00 02 y e a r 00 ?? 1301</pre> 1302When writing code to extract data from named subpatterns using the 1303name-to-number map, remember that the length of the entries is likely to be 1304different for each compiled pattern. 1305<pre> 1306 PCRE_INFO_OKPARTIAL 1307</pre> 1308Return 1 if the pattern can be used for partial matching with 1309<b>pcre_exec()</b>, otherwise 0. The fourth argument should point to an 1310<b>int</b> variable. From release 8.00, this always returns 1, because the 1311restrictions that previously applied to partial matching have been lifted. The 1312<a href="pcrepartial.html"><b>pcrepartial</b></a> 1313documentation gives details of partial matching. 1314<pre> 1315 PCRE_INFO_OPTIONS 1316</pre> 1317Return a copy of the options with which the pattern was compiled. The fourth 1318argument should point to an <b>unsigned long int</b> variable. These option bits 1319are those specified in the call to <b>pcre_compile()</b>, modified by any 1320top-level option settings at the start of the pattern itself. In other words, 1321they are the options that will be in force when matching starts. For example, 1322if the pattern /(?im)abc(?-i)d/ is compiled with the PCRE_EXTENDED option, the 1323result is PCRE_CASELESS, PCRE_MULTILINE, and PCRE_EXTENDED. 1324</P> 1325<P> 1326A pattern is automatically anchored by PCRE if all of its top-level 1327alternatives begin with one of the following: 1328<pre> 1329 ^ unless PCRE_MULTILINE is set 1330 \A always 1331 \G always 1332 .* if PCRE_DOTALL is set and there are no back references to the subpattern in which .* appears 1333</pre> 1334For such patterns, the PCRE_ANCHORED bit is set in the options returned by 1335<b>pcre_fullinfo()</b>. 1336<pre> 1337 PCRE_INFO_SIZE 1338</pre> 1339Return the size of the compiled pattern in bytes (for both libraries). The 1340fourth argument should point to a <b>size_t</b> variable. This value does not 1341include the size of the <b>pcre</b> structure that is returned by 1342<b>pcre_compile()</b>. The value that is passed as the argument to 1343<b>pcre_malloc()</b> when <b>pcre_compile()</b> is getting memory in which to 1344place the compiled data is the value returned by this option plus the size of 1345the <b>pcre</b> structure. Studying a compiled pattern, with or without JIT, 1346does not alter the value returned by this option. 1347<pre> 1348 PCRE_INFO_STUDYSIZE 1349</pre> 1350Return the size in bytes of the data block pointed to by the <i>study_data</i> 1351field in a <b>pcre_extra</b> block. If <b>pcre_extra</b> is NULL, or there is no 1352study data, zero is returned. The fourth argument should point to a 1353<b>size_t</b> variable. The <i>study_data</i> field is set by <b>pcre_study()</b> 1354to record information that will speed up matching (see the section entitled 1355<a href="#studyingapattern">"Studying a pattern"</a> 1356above). The format of the <i>study_data</i> block is private, but its length 1357is made available via this option so that it can be saved and restored (see the 1358<a href="pcreprecompile.html"><b>pcreprecompile</b></a> 1359documentation for details). 1360</P> 1361<br><a name="SEC16" href="#TOC1">REFERENCE COUNTS</a><br> 1362<P> 1363<b>int pcre_refcount(pcre *<i>code</i>, int <i>adjust</i>);</b> 1364</P> 1365<P> 1366The <b>pcre_refcount()</b> function is used to maintain a reference count in the 1367data block that contains a compiled pattern. It is provided for the benefit of 1368applications that operate in an object-oriented manner, where different parts 1369of the application may be using the same compiled pattern, but you want to free 1370the block when they are all done. 1371</P> 1372<P> 1373When a pattern is compiled, the reference count field is initialized to zero. 1374It is changed only by calling this function, whose action is to add the 1375<i>adjust</i> value (which may be positive or negative) to it. The yield of the 1376function is the new value. However, the value of the count is constrained to 1377lie between 0 and 65535, inclusive. If the new value is outside these limits, 1378it is forced to the appropriate limit value. 1379</P> 1380<P> 1381Except when it is zero, the reference count is not correctly preserved if a 1382pattern is compiled on one host and then transferred to a host whose byte-order 1383is different. (This seems a highly unlikely scenario.) 1384</P> 1385<br><a name="SEC17" href="#TOC1">MATCHING A PATTERN: THE TRADITIONAL FUNCTION</a><br> 1386<P> 1387<b>int pcre_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> 1388<b>const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b> 1389<b>int <i>options</i>, int *<i>ovector</i>, int <i>ovecsize</i>);</b> 1390</P> 1391<P> 1392The function <b>pcre_exec()</b> is called to match a subject string against a 1393compiled pattern, which is passed in the <i>code</i> argument. If the 1394pattern was studied, the result of the study should be passed in the 1395<i>extra</i> argument. You can call <b>pcre_exec()</b> with the same <i>code</i> 1396and <i>extra</i> arguments as many times as you like, in order to match 1397different subject strings with the same pattern. 1398</P> 1399<P> 1400This function is the main matching facility of the library, and it operates in 1401a Perl-like manner. For specialist use there is also an alternative matching 1402function, which is described 1403<a href="#dfamatch">below</a> 1404in the section about the <b>pcre_dfa_exec()</b> function. 1405</P> 1406<P> 1407In most applications, the pattern will have been compiled (and optionally 1408studied) in the same process that calls <b>pcre_exec()</b>. However, it is 1409possible to save compiled patterns and study data, and then use them later 1410in different processes, possibly even on different hosts. For a discussion 1411about this, see the 1412<a href="pcreprecompile.html"><b>pcreprecompile</b></a> 1413documentation. 1414</P> 1415<P> 1416Here is an example of a simple call to <b>pcre_exec()</b>: 1417<pre> 1418 int rc; 1419 int ovector[30]; 1420 rc = pcre_exec( 1421 re, /* result of pcre_compile() */ 1422 NULL, /* we didn't study the pattern */ 1423 "some string", /* the subject string */ 1424 11, /* the length of the subject string */ 1425 0, /* start at offset 0 in the subject */ 1426 0, /* default options */ 1427 ovector, /* vector of integers for substring information */ 1428 30); /* number of elements (NOT size in bytes) */ 1429<a name="extradata"></a></PRE> 1430</P> 1431<br><b> 1432Extra data for <b>pcre_exec()</b> 1433</b><br> 1434<P> 1435If the <i>extra</i> argument is not NULL, it must point to a <b>pcre_extra</b> 1436data block. The <b>pcre_study()</b> function returns such a block (when it 1437doesn't return NULL), but you can also create one for yourself, and pass 1438additional information in it. The <b>pcre_extra</b> block contains the following 1439fields (not necessarily in this order): 1440<pre> 1441 unsigned long int <i>flags</i>; 1442 void *<i>study_data</i>; 1443 void *<i>executable_jit</i>; 1444 unsigned long int <i>match_limit</i>; 1445 unsigned long int <i>match_limit_recursion</i>; 1446 void *<i>callout_data</i>; 1447 const unsigned char *<i>tables</i>; 1448 unsigned char **<i>mark</i>; 1449</pre> 1450In the 16-bit version of this structure, the <i>mark</i> field has type 1451"PCRE_UCHAR16 **". 1452</P> 1453<P> 1454The <i>flags</i> field is used to specify which of the other fields are set. The 1455flag bits are: 1456<pre> 1457 PCRE_EXTRA_CALLOUT_DATA 1458 PCRE_EXTRA_EXECUTABLE_JIT 1459 PCRE_EXTRA_MARK 1460 PCRE_EXTRA_MATCH_LIMIT 1461 PCRE_EXTRA_MATCH_LIMIT_RECURSION 1462 PCRE_EXTRA_STUDY_DATA 1463 PCRE_EXTRA_TABLES 1464</pre> 1465Other flag bits should be set to zero. The <i>study_data</i> field and sometimes 1466the <i>executable_jit</i> field are set in the <b>pcre_extra</b> block that is 1467returned by <b>pcre_study()</b>, together with the appropriate flag bits. You 1468should not set these yourself, but you may add to the block by setting other 1469fields and their corresponding flag bits. 1470</P> 1471<P> 1472The <i>match_limit</i> field provides a means of preventing PCRE from using up a 1473vast amount of resources when running patterns that are not going to match, 1474but which have a very large number of possibilities in their search trees. The 1475classic example is a pattern that uses nested unlimited repeats. 1476</P> 1477<P> 1478Internally, <b>pcre_exec()</b> uses a function called <b>match()</b>, which it 1479calls repeatedly (sometimes recursively). The limit set by <i>match_limit</i> is 1480imposed on the number of times this function is called during a match, which 1481has the effect of limiting the amount of backtracking that can take place. For 1482patterns that are not anchored, the count restarts from zero for each position 1483in the subject string. 1484</P> 1485<P> 1486When <b>pcre_exec()</b> is called with a pattern that was successfully studied 1487with a JIT option, the way that the matching is executed is entirely different. 1488However, there is still the possibility of runaway matching that goes on for a 1489very long time, and so the <i>match_limit</i> value is also used in this case 1490(but in a different way) to limit how long the matching can continue. 1491</P> 1492<P> 1493The default value for the limit can be set when PCRE is built; the default 1494default is 10 million, which handles all but the most extreme cases. You can 1495override the default by suppling <b>pcre_exec()</b> with a <b>pcre_extra</b> 1496block in which <i>match_limit</i> is set, and PCRE_EXTRA_MATCH_LIMIT is set in 1497the <i>flags</i> field. If the limit is exceeded, <b>pcre_exec()</b> returns 1498PCRE_ERROR_MATCHLIMIT. 1499</P> 1500<P> 1501The <i>match_limit_recursion</i> field is similar to <i>match_limit</i>, but 1502instead of limiting the total number of times that <b>match()</b> is called, it 1503limits the depth of recursion. The recursion depth is a smaller number than the 1504total number of calls, because not all calls to <b>match()</b> are recursive. 1505This limit is of use only if it is set smaller than <i>match_limit</i>. 1506</P> 1507<P> 1508Limiting the recursion depth limits the amount of machine stack that can be 1509used, or, when PCRE has been compiled to use memory on the heap instead of the 1510stack, the amount of heap memory that can be used. This limit is not relevant, 1511and is ignored, when matching is done using JIT compiled code. 1512</P> 1513<P> 1514The default value for <i>match_limit_recursion</i> can be set when PCRE is 1515built; the default default is the same value as the default for 1516<i>match_limit</i>. You can override the default by suppling <b>pcre_exec()</b> 1517with a <b>pcre_extra</b> block in which <i>match_limit_recursion</i> is set, and 1518PCRE_EXTRA_MATCH_LIMIT_RECURSION is set in the <i>flags</i> field. If the limit 1519is exceeded, <b>pcre_exec()</b> returns PCRE_ERROR_RECURSIONLIMIT. 1520</P> 1521<P> 1522The <i>callout_data</i> field is used in conjunction with the "callout" feature, 1523and is described in the 1524<a href="pcrecallout.html"><b>pcrecallout</b></a> 1525documentation. 1526</P> 1527<P> 1528The <i>tables</i> field is used to pass a character tables pointer to 1529<b>pcre_exec()</b>; this overrides the value that is stored with the compiled 1530pattern. A non-NULL value is stored with the compiled pattern only if custom 1531tables were supplied to <b>pcre_compile()</b> via its <i>tableptr</i> argument. 1532If NULL is passed to <b>pcre_exec()</b> using this mechanism, it forces PCRE's 1533internal tables to be used. This facility is helpful when re-using patterns 1534that have been saved after compiling with an external set of tables, because 1535the external tables might be at a different address when <b>pcre_exec()</b> is 1536called. See the 1537<a href="pcreprecompile.html"><b>pcreprecompile</b></a> 1538documentation for a discussion of saving compiled patterns for later use. 1539</P> 1540<P> 1541If PCRE_EXTRA_MARK is set in the <i>flags</i> field, the <i>mark</i> field must 1542be set to point to a suitable variable. If the pattern contains any 1543backtracking control verbs such as (*MARK:NAME), and the execution ends up with 1544a name to pass back, a pointer to the name string (zero terminated) is placed 1545in the variable pointed to by the <i>mark</i> field. The names are within the 1546compiled pattern; if you wish to retain such a name you must copy it before 1547freeing the memory of a compiled pattern. If there is no name to pass back, the 1548variable pointed to by the <i>mark</i> field is set to NULL. For details of the 1549backtracking control verbs, see the section entitled 1550<a href="pcrepattern#backtrackcontrol">"Backtracking control"</a> 1551in the 1552<a href="pcrepattern.html"><b>pcrepattern</b></a> 1553documentation. 1554<a name="execoptions"></a></P> 1555<br><b> 1556Option bits for <b>pcre_exec()</b> 1557</b><br> 1558<P> 1559The unused bits of the <i>options</i> argument for <b>pcre_exec()</b> must be 1560zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_<i>xxx</i>, 1561PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART, 1562PCRE_NO_START_OPTIMIZE, PCRE_NO_UTF8_CHECK, PCRE_PARTIAL_HARD, and 1563PCRE_PARTIAL_SOFT. 1564</P> 1565<P> 1566If the pattern was successfully studied with one of the just-in-time (JIT) 1567compile options, the only supported options for JIT execution are 1568PCRE_NO_UTF8_CHECK, PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, 1569PCRE_NOTEMPTY_ATSTART, PCRE_PARTIAL_HARD, and PCRE_PARTIAL_SOFT. If an 1570unsupported option is used, JIT execution is disabled and the normal 1571interpretive code in <b>pcre_exec()</b> is run. 1572<pre> 1573 PCRE_ANCHORED 1574</pre> 1575The PCRE_ANCHORED option limits <b>pcre_exec()</b> to matching at the first 1576matching position. If a pattern was compiled with PCRE_ANCHORED, or turned out 1577to be anchored by virtue of its contents, it cannot be made unachored at 1578matching time. 1579<pre> 1580 PCRE_BSR_ANYCRLF 1581 PCRE_BSR_UNICODE 1582</pre> 1583These options (which are mutually exclusive) control what the \R escape 1584sequence matches. The choice is either to match only CR, LF, or CRLF, or to 1585match any Unicode newline sequence. These options override the choice that was 1586made or defaulted when the pattern was compiled. 1587<pre> 1588 PCRE_NEWLINE_CR 1589 PCRE_NEWLINE_LF 1590 PCRE_NEWLINE_CRLF 1591 PCRE_NEWLINE_ANYCRLF 1592 PCRE_NEWLINE_ANY 1593</pre> 1594These options override the newline definition that was chosen or defaulted when 1595the pattern was compiled. For details, see the description of 1596<b>pcre_compile()</b> above. During matching, the newline choice affects the 1597behaviour of the dot, circumflex, and dollar metacharacters. It may also alter 1598the way the match position is advanced after a match failure for an unanchored 1599pattern. 1600</P> 1601<P> 1602When PCRE_NEWLINE_CRLF, PCRE_NEWLINE_ANYCRLF, or PCRE_NEWLINE_ANY is set, and a 1603match attempt for an unanchored pattern fails when the current position is at a 1604CRLF sequence, and the pattern contains no explicit matches for CR or LF 1605characters, the match position is advanced by two characters instead of one, in 1606other words, to after the CRLF. 1607</P> 1608<P> 1609The above rule is a compromise that makes the most common cases work as 1610expected. For example, if the pattern is .+A (and the PCRE_DOTALL option is not 1611set), it does not match the string "\r\nA" because, after failing at the 1612start, it skips both the CR and the LF before retrying. However, the pattern 1613[\r\n]A does match that string, because it contains an explicit CR or LF 1614reference, and so advances only by one character after the first failure. 1615</P> 1616<P> 1617An explicit match for CR of LF is either a literal appearance of one of those 1618characters, or one of the \r or \n escape sequences. Implicit matches such as 1619[^X] do not count, nor does \s (which includes CR and LF in the characters 1620that it matches). 1621</P> 1622<P> 1623Notwithstanding the above, anomalous effects may still occur when CRLF is a 1624valid newline sequence and explicit \r or \n escapes appear in the pattern. 1625<pre> 1626 PCRE_NOTBOL 1627</pre> 1628This option specifies that first character of the subject string is not the 1629beginning of a line, so the circumflex metacharacter should not match before 1630it. Setting this without PCRE_MULTILINE (at compile time) causes circumflex 1631never to match. This option affects only the behaviour of the circumflex 1632metacharacter. It does not affect \A. 1633<pre> 1634 PCRE_NOTEOL 1635</pre> 1636This option specifies that the end of the subject string is not the end of a 1637line, so the dollar metacharacter should not match it nor (except in multiline 1638mode) a newline immediately before it. Setting this without PCRE_MULTILINE (at 1639compile time) causes dollar never to match. This option affects only the 1640behaviour of the dollar metacharacter. It does not affect \Z or \z. 1641<pre> 1642 PCRE_NOTEMPTY 1643</pre> 1644An empty string is not considered to be a valid match if this option is set. If 1645there are alternatives in the pattern, they are tried. If all the alternatives 1646match the empty string, the entire match fails. For example, if the pattern 1647<pre> 1648 a?b? 1649</pre> 1650is applied to a string not beginning with "a" or "b", it matches an empty 1651string at the start of the subject. With PCRE_NOTEMPTY set, this match is not 1652valid, so PCRE searches further into the string for occurrences of "a" or "b". 1653<pre> 1654 PCRE_NOTEMPTY_ATSTART 1655</pre> 1656This is like PCRE_NOTEMPTY, except that an empty string match that is not at 1657the start of the subject is permitted. If the pattern is anchored, such a match 1658can occur only if the pattern contains \K. 1659</P> 1660<P> 1661Perl has no direct equivalent of PCRE_NOTEMPTY or PCRE_NOTEMPTY_ATSTART, but it 1662does make a special case of a pattern match of the empty string within its 1663<b>split()</b> function, and when using the /g modifier. It is possible to 1664emulate Perl's behaviour after matching a null string by first trying the match 1665again at the same offset with PCRE_NOTEMPTY_ATSTART and PCRE_ANCHORED, and then 1666if that fails, by advancing the starting offset (see below) and trying an 1667ordinary match again. There is some code that demonstrates how to do this in 1668the 1669<a href="pcredemo.html"><b>pcredemo</b></a> 1670sample program. In the most general case, you have to check to see if the 1671newline convention recognizes CRLF as a newline, and if so, and the current 1672character is CR followed by LF, advance the starting offset by two characters 1673instead of one. 1674<pre> 1675 PCRE_NO_START_OPTIMIZE 1676</pre> 1677There are a number of optimizations that <b>pcre_exec()</b> uses at the start of 1678a match, in order to speed up the process. For example, if it is known that an 1679unanchored match must start with a specific character, it searches the subject 1680for that character, and fails immediately if it cannot find it, without 1681actually running the main matching function. This means that a special item 1682such as (*COMMIT) at the start of a pattern is not considered until after a 1683suitable starting point for the match has been found. When callouts or (*MARK) 1684items are in use, these "start-up" optimizations can cause them to be skipped 1685if the pattern is never actually used. The start-up optimizations are in effect 1686a pre-scan of the subject that takes place before the pattern is run. 1687</P> 1688<P> 1689The PCRE_NO_START_OPTIMIZE option disables the start-up optimizations, possibly 1690causing performance to suffer, but ensuring that in cases where the result is 1691"no match", the callouts do occur, and that items such as (*COMMIT) and (*MARK) 1692are considered at every possible starting position in the subject string. If 1693PCRE_NO_START_OPTIMIZE is set at compile time, it cannot be unset at matching 1694time. The use of PCRE_NO_START_OPTIMIZE disables JIT execution; when it is set, 1695matching is always done using interpretively. 1696</P> 1697<P> 1698Setting PCRE_NO_START_OPTIMIZE can change the outcome of a matching operation. 1699Consider the pattern 1700<pre> 1701 (*COMMIT)ABC 1702</pre> 1703When this is compiled, PCRE records the fact that a match must start with the 1704character "A". Suppose the subject string is "DEFABC". The start-up 1705optimization scans along the subject, finds "A" and runs the first match 1706attempt from there. The (*COMMIT) item means that the pattern must match the 1707current starting position, which in this case, it does. However, if the same 1708match is run with PCRE_NO_START_OPTIMIZE set, the initial scan along the 1709subject string does not happen. The first match attempt is run starting from 1710"D" and when this fails, (*COMMIT) prevents any further matches being tried, so 1711the overall result is "no match". If the pattern is studied, more start-up 1712optimizations may be used. For example, a minimum length for the subject may be 1713recorded. Consider the pattern 1714<pre> 1715 (*MARK:A)(X|Y) 1716</pre> 1717The minimum length for a match is one character. If the subject is "ABC", there 1718will be attempts to match "ABC", "BC", "C", and then finally an empty string. 1719If the pattern is studied, the final attempt does not take place, because PCRE 1720knows that the subject is too short, and so the (*MARK) is never encountered. 1721In this case, studying the pattern does not affect the overall match result, 1722which is still "no match", but it does affect the auxiliary information that is 1723returned. 1724<pre> 1725 PCRE_NO_UTF8_CHECK 1726</pre> 1727When PCRE_UTF8 is set at compile time, the validity of the subject as a UTF-8 1728string is automatically checked when <b>pcre_exec()</b> is subsequently called. 1729The entire string is checked before any other processing takes place. The value 1730of <i>startoffset</i> is also checked to ensure that it points to the start of a 1731UTF-8 character. There is a discussion about the 1732<a href="pcreunicode.html#utf8strings">validity of UTF-8 strings</a> 1733in the 1734<a href="pcreunicode.html"><b>pcreunicode</b></a> 1735page. If an invalid sequence of bytes is found, <b>pcre_exec()</b> returns the 1736error PCRE_ERROR_BADUTF8 or, if PCRE_PARTIAL_HARD is set and the problem is a 1737truncated character at the end of the subject, PCRE_ERROR_SHORTUTF8. In both 1738cases, information about the precise nature of the error may also be returned 1739(see the descriptions of these errors in the section entitled \fIError return 1740values from\fP <b>pcre_exec()</b> 1741<a href="#errorlist">below).</a> 1742If <i>startoffset</i> contains a value that does not point to the start of a 1743UTF-8 character (or to the end of the subject), PCRE_ERROR_BADUTF8_OFFSET is 1744returned. 1745</P> 1746<P> 1747If you already know that your subject is valid, and you want to skip these 1748checks for performance reasons, you can set the PCRE_NO_UTF8_CHECK option when 1749calling <b>pcre_exec()</b>. You might want to do this for the second and 1750subsequent calls to <b>pcre_exec()</b> if you are making repeated calls to find 1751all the matches in a single subject string. However, you should be sure that 1752the value of <i>startoffset</i> points to the start of a character (or the end 1753of the subject). When PCRE_NO_UTF8_CHECK is set, the effect of passing an 1754invalid string as a subject or an invalid value of <i>startoffset</i> is 1755undefined. Your program may crash. 1756<pre> 1757 PCRE_PARTIAL_HARD 1758 PCRE_PARTIAL_SOFT 1759</pre> 1760These options turn on the partial matching feature. For backwards 1761compatibility, PCRE_PARTIAL is a synonym for PCRE_PARTIAL_SOFT. A partial match 1762occurs if the end of the subject string is reached successfully, but there are 1763not enough subject characters to complete the match. If this happens when 1764PCRE_PARTIAL_SOFT (but not PCRE_PARTIAL_HARD) is set, matching continues by 1765testing any remaining alternatives. Only if no complete match can be found is 1766PCRE_ERROR_PARTIAL returned instead of PCRE_ERROR_NOMATCH. In other words, 1767PCRE_PARTIAL_SOFT says that the caller is prepared to handle a partial match, 1768but only if no complete match can be found. 1769</P> 1770<P> 1771If PCRE_PARTIAL_HARD is set, it overrides PCRE_PARTIAL_SOFT. In this case, if a 1772partial match is found, <b>pcre_exec()</b> immediately returns 1773PCRE_ERROR_PARTIAL, without considering any other alternatives. In other words, 1774when PCRE_PARTIAL_HARD is set, a partial match is considered to be more 1775important that an alternative complete match. 1776</P> 1777<P> 1778In both cases, the portion of the string that was inspected when the partial 1779match was found is set as the first matching string. There is a more detailed 1780discussion of partial and multi-segment matching, with examples, in the 1781<a href="pcrepartial.html"><b>pcrepartial</b></a> 1782documentation. 1783</P> 1784<br><b> 1785The string to be matched by <b>pcre_exec()</b> 1786</b><br> 1787<P> 1788The subject string is passed to <b>pcre_exec()</b> as a pointer in 1789<i>subject</i>, a length in bytes in <i>length</i>, and a starting byte offset 1790in <i>startoffset</i>. If this is negative or greater than the length of the 1791subject, <b>pcre_exec()</b> returns PCRE_ERROR_BADOFFSET. When the starting 1792offset is zero, the search for a match starts at the beginning of the subject, 1793and this is by far the most common case. In UTF-8 mode, the byte offset must 1794point to the start of a UTF-8 character (or the end of the subject). Unlike the 1795pattern string, the subject may contain binary zero bytes. 1796</P> 1797<P> 1798A non-zero starting offset is useful when searching for another match in the 1799same subject by calling <b>pcre_exec()</b> again after a previous success. 1800Setting <i>startoffset</i> differs from just passing over a shortened string and 1801setting PCRE_NOTBOL in the case of a pattern that begins with any kind of 1802lookbehind. For example, consider the pattern 1803<pre> 1804 \Biss\B 1805</pre> 1806which finds occurrences of "iss" in the middle of words. (\B matches only if 1807the current position in the subject is not a word boundary.) When applied to 1808the string "Mississipi" the first call to <b>pcre_exec()</b> finds the first 1809occurrence. If <b>pcre_exec()</b> is called again with just the remainder of the 1810subject, namely "issipi", it does not match, because \B is always false at the 1811start of the subject, which is deemed to be a word boundary. However, if 1812<b>pcre_exec()</b> is passed the entire string again, but with <i>startoffset</i> 1813set to 4, it finds the second occurrence of "iss" because it is able to look 1814behind the starting point to discover that it is preceded by a letter. 1815</P> 1816<P> 1817Finding all the matches in a subject is tricky when the pattern can match an 1818empty string. It is possible to emulate Perl's /g behaviour by first trying the 1819match again at the same offset, with the PCRE_NOTEMPTY_ATSTART and 1820PCRE_ANCHORED options, and then if that fails, advancing the starting offset 1821and trying an ordinary match again. There is some code that demonstrates how to 1822do this in the 1823<a href="pcredemo.html"><b>pcredemo</b></a> 1824sample program. In the most general case, you have to check to see if the 1825newline convention recognizes CRLF as a newline, and if so, and the current 1826character is CR followed by LF, advance the starting offset by two characters 1827instead of one. 1828</P> 1829<P> 1830If a non-zero starting offset is passed when the pattern is anchored, one 1831attempt to match at the given offset is made. This can only succeed if the 1832pattern does not require the match to be at the start of the subject. 1833</P> 1834<br><b> 1835How <b>pcre_exec()</b> returns captured substrings 1836</b><br> 1837<P> 1838In general, a pattern matches a certain portion of the subject, and in 1839addition, further substrings from the subject may be picked out by parts of the 1840pattern. Following the usage in Jeffrey Friedl's book, this is called 1841"capturing" in what follows, and the phrase "capturing subpattern" is used for 1842a fragment of a pattern that picks out a substring. PCRE supports several other 1843kinds of parenthesized subpattern that do not cause substrings to be captured. 1844</P> 1845<P> 1846Captured substrings are returned to the caller via a vector of integers whose 1847address is passed in <i>ovector</i>. The number of elements in the vector is 1848passed in <i>ovecsize</i>, which must be a non-negative number. <b>Note</b>: this 1849argument is NOT the size of <i>ovector</i> in bytes. 1850</P> 1851<P> 1852The first two-thirds of the vector is used to pass back captured substrings, 1853each substring using a pair of integers. The remaining third of the vector is 1854used as workspace by <b>pcre_exec()</b> while matching capturing subpatterns, 1855and is not available for passing back information. The number passed in 1856<i>ovecsize</i> should always be a multiple of three. If it is not, it is 1857rounded down. 1858</P> 1859<P> 1860When a match is successful, information about captured substrings is returned 1861in pairs of integers, starting at the beginning of <i>ovector</i>, and 1862continuing up to two-thirds of its length at the most. The first element of 1863each pair is set to the byte offset of the first character in a substring, and 1864the second is set to the byte offset of the first character after the end of a 1865substring. <b>Note</b>: these values are always byte offsets, even in UTF-8 1866mode. They are not character counts. 1867</P> 1868<P> 1869The first pair of integers, <i>ovector[0]</i> and <i>ovector[1]</i>, identify the 1870portion of the subject string matched by the entire pattern. The next pair is 1871used for the first capturing subpattern, and so on. The value returned by 1872<b>pcre_exec()</b> is one more than the highest numbered pair that has been set. 1873For example, if two substrings have been captured, the returned value is 3. If 1874there are no capturing subpatterns, the return value from a successful match is 18751, indicating that just the first pair of offsets has been set. 1876</P> 1877<P> 1878If a capturing subpattern is matched repeatedly, it is the last portion of the 1879string that it matched that is returned. 1880</P> 1881<P> 1882If the vector is too small to hold all the captured substring offsets, it is 1883used as far as possible (up to two-thirds of its length), and the function 1884returns a value of zero. If neither the actual string matched nor any captured 1885substrings are of interest, <b>pcre_exec()</b> may be called with <i>ovector</i> 1886passed as NULL and <i>ovecsize</i> as zero. However, if the pattern contains 1887back references and the <i>ovector</i> is not big enough to remember the related 1888substrings, PCRE has to get additional memory for use during matching. Thus it 1889is usually advisable to supply an <i>ovector</i> of reasonable size. 1890</P> 1891<P> 1892There are some cases where zero is returned (indicating vector overflow) when 1893in fact the vector is exactly the right size for the final match. For example, 1894consider the pattern 1895<pre> 1896 (a)(?:(b)c|bd) 1897</pre> 1898If a vector of 6 elements (allowing for only 1 captured substring) is given 1899with subject string "abd", <b>pcre_exec()</b> will try to set the second 1900captured string, thereby recording a vector overflow, before failing to match 1901"c" and backing up to try the second alternative. The zero return, however, 1902does correctly indicate that the maximum number of slots (namely 2) have been 1903filled. In similar cases where there is temporary overflow, but the final 1904number of used slots is actually less than the maximum, a non-zero value is 1905returned. 1906</P> 1907<P> 1908The <b>pcre_fullinfo()</b> function can be used to find out how many capturing 1909subpatterns there are in a compiled pattern. The smallest size for 1910<i>ovector</i> that will allow for <i>n</i> captured substrings, in addition to 1911the offsets of the substring matched by the whole pattern, is (<i>n</i>+1)*3. 1912</P> 1913<P> 1914It is possible for capturing subpattern number <i>n+1</i> to match some part of 1915the subject when subpattern <i>n</i> has not been used at all. For example, if 1916the string "abc" is matched against the pattern (a|(z))(bc) the return from the 1917function is 4, and subpatterns 1 and 3 are matched, but 2 is not. When this 1918happens, both values in the offset pairs corresponding to unused subpatterns 1919are set to -1. 1920</P> 1921<P> 1922Offset values that correspond to unused subpatterns at the end of the 1923expression are also set to -1. For example, if the string "abc" is matched 1924against the pattern (abc)(x(yz)?)? subpatterns 2 and 3 are not matched. The 1925return from the function is 2, because the highest used capturing subpattern 1926number is 1, and the offsets for for the second and third capturing subpatterns 1927(assuming the vector is large enough, of course) are set to -1. 1928</P> 1929<P> 1930<b>Note</b>: Elements in the first two-thirds of <i>ovector</i> that do not 1931correspond to capturing parentheses in the pattern are never changed. That is, 1932if a pattern contains <i>n</i> capturing parentheses, no more than 1933<i>ovector[0]</i> to <i>ovector[2n+1]</i> are set by <b>pcre_exec()</b>. The other 1934elements (in the first two-thirds) retain whatever values they previously had. 1935</P> 1936<P> 1937Some convenience functions are provided for extracting the captured substrings 1938as separate strings. These are described below. 1939<a name="errorlist"></a></P> 1940<br><b> 1941Error return values from <b>pcre_exec()</b> 1942</b><br> 1943<P> 1944If <b>pcre_exec()</b> fails, it returns a negative number. The following are 1945defined in the header file: 1946<pre> 1947 PCRE_ERROR_NOMATCH (-1) 1948</pre> 1949The subject string did not match the pattern. 1950<pre> 1951 PCRE_ERROR_NULL (-2) 1952</pre> 1953Either <i>code</i> or <i>subject</i> was passed as NULL, or <i>ovector</i> was 1954NULL and <i>ovecsize</i> was not zero. 1955<pre> 1956 PCRE_ERROR_BADOPTION (-3) 1957</pre> 1958An unrecognized bit was set in the <i>options</i> argument. 1959<pre> 1960 PCRE_ERROR_BADMAGIC (-4) 1961</pre> 1962PCRE stores a 4-byte "magic number" at the start of the compiled code, to catch 1963the case when it is passed a junk pointer and to detect when a pattern that was 1964compiled in an environment of one endianness is run in an environment with the 1965other endianness. This is the error that PCRE gives when the magic number is 1966not present. 1967<pre> 1968 PCRE_ERROR_UNKNOWN_OPCODE (-5) 1969</pre> 1970While running the pattern match, an unknown item was encountered in the 1971compiled pattern. This error could be caused by a bug in PCRE or by overwriting 1972of the compiled pattern. 1973<pre> 1974 PCRE_ERROR_NOMEMORY (-6) 1975</pre> 1976If a pattern contains back references, but the <i>ovector</i> that is passed to 1977<b>pcre_exec()</b> is not big enough to remember the referenced substrings, PCRE 1978gets a block of memory at the start of matching to use for this purpose. If the 1979call via <b>pcre_malloc()</b> fails, this error is given. The memory is 1980automatically freed at the end of matching. 1981</P> 1982<P> 1983This error is also given if <b>pcre_stack_malloc()</b> fails in 1984<b>pcre_exec()</b>. This can happen only when PCRE has been compiled with 1985<b>--disable-stack-for-recursion</b>. 1986<pre> 1987 PCRE_ERROR_NOSUBSTRING (-7) 1988</pre> 1989This error is used by the <b>pcre_copy_substring()</b>, 1990<b>pcre_get_substring()</b>, and <b>pcre_get_substring_list()</b> functions (see 1991below). It is never returned by <b>pcre_exec()</b>. 1992<pre> 1993 PCRE_ERROR_MATCHLIMIT (-8) 1994</pre> 1995The backtracking limit, as specified by the <i>match_limit</i> field in a 1996<b>pcre_extra</b> structure (or defaulted) was reached. See the description 1997above. 1998<pre> 1999 PCRE_ERROR_CALLOUT (-9) 2000</pre> 2001This error is never generated by <b>pcre_exec()</b> itself. It is provided for 2002use by callout functions that want to yield a distinctive error code. See the 2003<a href="pcrecallout.html"><b>pcrecallout</b></a> 2004documentation for details. 2005<pre> 2006 PCRE_ERROR_BADUTF8 (-10) 2007</pre> 2008A string that contains an invalid UTF-8 byte sequence was passed as a subject, 2009and the PCRE_NO_UTF8_CHECK option was not set. If the size of the output vector 2010(<i>ovecsize</i>) is at least 2, the byte offset to the start of the the invalid 2011UTF-8 character is placed in the first element, and a reason code is placed in 2012the second element. The reason codes are listed in the 2013<a href="#badutf8reasons">following section.</a> 2014For backward compatibility, if PCRE_PARTIAL_HARD is set and the problem is a 2015truncated UTF-8 character at the end of the subject (reason codes 1 to 5), 2016PCRE_ERROR_SHORTUTF8 is returned instead of PCRE_ERROR_BADUTF8. 2017<pre> 2018 PCRE_ERROR_BADUTF8_OFFSET (-11) 2019</pre> 2020The UTF-8 byte sequence that was passed as a subject was checked and found to 2021be valid (the PCRE_NO_UTF8_CHECK option was not set), but the value of 2022<i>startoffset</i> did not point to the beginning of a UTF-8 character or the 2023end of the subject. 2024<pre> 2025 PCRE_ERROR_PARTIAL (-12) 2026</pre> 2027The subject string did not match, but it did match partially. See the 2028<a href="pcrepartial.html"><b>pcrepartial</b></a> 2029documentation for details of partial matching. 2030<pre> 2031 PCRE_ERROR_BADPARTIAL (-13) 2032</pre> 2033This code is no longer in use. It was formerly returned when the PCRE_PARTIAL 2034option was used with a compiled pattern containing items that were not 2035supported for partial matching. From release 8.00 onwards, there are no 2036restrictions on partial matching. 2037<pre> 2038 PCRE_ERROR_INTERNAL (-14) 2039</pre> 2040An unexpected internal error has occurred. This error could be caused by a bug 2041in PCRE or by overwriting of the compiled pattern. 2042<pre> 2043 PCRE_ERROR_BADCOUNT (-15) 2044</pre> 2045This error is given if the value of the <i>ovecsize</i> argument is negative. 2046<pre> 2047 PCRE_ERROR_RECURSIONLIMIT (-21) 2048</pre> 2049The internal recursion limit, as specified by the <i>match_limit_recursion</i> 2050field in a <b>pcre_extra</b> structure (or defaulted) was reached. See the 2051description above. 2052<pre> 2053 PCRE_ERROR_BADNEWLINE (-23) 2054</pre> 2055An invalid combination of PCRE_NEWLINE_<i>xxx</i> options was given. 2056<pre> 2057 PCRE_ERROR_BADOFFSET (-24) 2058</pre> 2059The value of <i>startoffset</i> was negative or greater than the length of the 2060subject, that is, the value in <i>length</i>. 2061<pre> 2062 PCRE_ERROR_SHORTUTF8 (-25) 2063</pre> 2064This error is returned instead of PCRE_ERROR_BADUTF8 when the subject string 2065ends with a truncated UTF-8 character and the PCRE_PARTIAL_HARD option is set. 2066Information about the failure is returned as for PCRE_ERROR_BADUTF8. It is in 2067fact sufficient to detect this case, but this special error code for 2068PCRE_PARTIAL_HARD precedes the implementation of returned information; it is 2069retained for backwards compatibility. 2070<pre> 2071 PCRE_ERROR_RECURSELOOP (-26) 2072</pre> 2073This error is returned when <b>pcre_exec()</b> detects a recursion loop within 2074the pattern. Specifically, it means that either the whole pattern or a 2075subpattern has been called recursively for the second time at the same position 2076in the subject string. Some simple patterns that might do this are detected and 2077faulted at compile time, but more complicated cases, in particular mutual 2078recursions between two different subpatterns, cannot be detected until run 2079time. 2080<pre> 2081 PCRE_ERROR_JIT_STACKLIMIT (-27) 2082</pre> 2083This error is returned when a pattern that was successfully studied using a 2084JIT compile option is being matched, but the memory available for the 2085just-in-time processing stack is not large enough. See the 2086<a href="pcrejit.html"><b>pcrejit</b></a> 2087documentation for more details. 2088<pre> 2089 PCRE_ERROR_BADMODE (-28) 2090</pre> 2091This error is given if a pattern that was compiled by the 8-bit library is 2092passed to a 16-bit library function, or vice versa. 2093<pre> 2094 PCRE_ERROR_BADENDIANNESS (-29) 2095</pre> 2096This error is given if a pattern that was compiled and saved is reloaded on a 2097host with different endianness. The utility function 2098<b>pcre_pattern_to_host_byte_order()</b> can be used to convert such a pattern 2099so that it runs on the new host. 2100</P> 2101<P> 2102Error numbers -16 to -20, -22, and -30 are not used by <b>pcre_exec()</b>. 2103<a name="badutf8reasons"></a></P> 2104<br><b> 2105Reason codes for invalid UTF-8 strings 2106</b><br> 2107<P> 2108This section applies only to the 8-bit library. The corresponding information 2109for the 16-bit library is given in the 2110<a href="pcre16.html"><b>pcre16</b></a> 2111page. 2112</P> 2113<P> 2114When <b>pcre_exec()</b> returns either PCRE_ERROR_BADUTF8 or 2115PCRE_ERROR_SHORTUTF8, and the size of the output vector (<i>ovecsize</i>) is at 2116least 2, the offset of the start of the invalid UTF-8 character is placed in 2117the first output vector element (<i>ovector[0]</i>) and a reason code is placed 2118in the second element (<i>ovector[1]</i>). The reason codes are given names in 2119the <b>pcre.h</b> header file: 2120<pre> 2121 PCRE_UTF8_ERR1 2122 PCRE_UTF8_ERR2 2123 PCRE_UTF8_ERR3 2124 PCRE_UTF8_ERR4 2125 PCRE_UTF8_ERR5 2126</pre> 2127The string ends with a truncated UTF-8 character; the code specifies how many 2128bytes are missing (1 to 5). Although RFC 3629 restricts UTF-8 characters to be 2129no longer than 4 bytes, the encoding scheme (originally defined by RFC 2279) 2130allows for up to 6 bytes, and this is checked first; hence the possibility of 21314 or 5 missing bytes. 2132<pre> 2133 PCRE_UTF8_ERR6 2134 PCRE_UTF8_ERR7 2135 PCRE_UTF8_ERR8 2136 PCRE_UTF8_ERR9 2137 PCRE_UTF8_ERR10 2138</pre> 2139The two most significant bits of the 2nd, 3rd, 4th, 5th, or 6th byte of the 2140character do not have the binary value 0b10 (that is, either the most 2141significant bit is 0, or the next bit is 1). 2142<pre> 2143 PCRE_UTF8_ERR11 2144 PCRE_UTF8_ERR12 2145</pre> 2146A character that is valid by the RFC 2279 rules is either 5 or 6 bytes long; 2147these code points are excluded by RFC 3629. 2148<pre> 2149 PCRE_UTF8_ERR13 2150</pre> 2151A 4-byte character has a value greater than 0x10fff; these code points are 2152excluded by RFC 3629. 2153<pre> 2154 PCRE_UTF8_ERR14 2155</pre> 2156A 3-byte character has a value in the range 0xd800 to 0xdfff; this range of 2157code points are reserved by RFC 3629 for use with UTF-16, and so are excluded 2158from UTF-8. 2159<pre> 2160 PCRE_UTF8_ERR15 2161 PCRE_UTF8_ERR16 2162 PCRE_UTF8_ERR17 2163 PCRE_UTF8_ERR18 2164 PCRE_UTF8_ERR19 2165</pre> 2166A 2-, 3-, 4-, 5-, or 6-byte character is "overlong", that is, it codes for a 2167value that can be represented by fewer bytes, which is invalid. For example, 2168the two bytes 0xc0, 0xae give the value 0x2e, whose correct coding uses just 2169one byte. 2170<pre> 2171 PCRE_UTF8_ERR20 2172</pre> 2173The two most significant bits of the first byte of a character have the binary 2174value 0b10 (that is, the most significant bit is 1 and the second is 0). Such a 2175byte can only validly occur as the second or subsequent byte of a multi-byte 2176character. 2177<pre> 2178 PCRE_UTF8_ERR21 2179</pre> 2180The first byte of a character has the value 0xfe or 0xff. These values can 2181never occur in a valid UTF-8 string. 2182</P> 2183<br><a name="SEC18" href="#TOC1">EXTRACTING CAPTURED SUBSTRINGS BY NUMBER</a><br> 2184<P> 2185<b>int pcre_copy_substring(const char *<i>subject</i>, int *<i>ovector</i>,</b> 2186<b>int <i>stringcount</i>, int <i>stringnumber</i>, char *<i>buffer</i>,</b> 2187<b>int <i>buffersize</i>);</b> 2188</P> 2189<P> 2190<b>int pcre_get_substring(const char *<i>subject</i>, int *<i>ovector</i>,</b> 2191<b>int <i>stringcount</i>, int <i>stringnumber</i>,</b> 2192<b>const char **<i>stringptr</i>);</b> 2193</P> 2194<P> 2195<b>int pcre_get_substring_list(const char *<i>subject</i>,</b> 2196<b>int *<i>ovector</i>, int <i>stringcount</i>, const char ***<i>listptr</i>);</b> 2197</P> 2198<P> 2199Captured substrings can be accessed directly by using the offsets returned by 2200<b>pcre_exec()</b> in <i>ovector</i>. For convenience, the functions 2201<b>pcre_copy_substring()</b>, <b>pcre_get_substring()</b>, and 2202<b>pcre_get_substring_list()</b> are provided for extracting captured substrings 2203as new, separate, zero-terminated strings. These functions identify substrings 2204by number. The next section describes functions for extracting named 2205substrings. 2206</P> 2207<P> 2208A substring that contains a binary zero is correctly extracted and has a 2209further zero added on the end, but the result is not, of course, a C string. 2210However, you can process such a string by referring to the length that is 2211returned by <b>pcre_copy_substring()</b> and <b>pcre_get_substring()</b>. 2212Unfortunately, the interface to <b>pcre_get_substring_list()</b> is not adequate 2213for handling strings containing binary zeros, because the end of the final 2214string is not independently indicated. 2215</P> 2216<P> 2217The first three arguments are the same for all three of these functions: 2218<i>subject</i> is the subject string that has just been successfully matched, 2219<i>ovector</i> is a pointer to the vector of integer offsets that was passed to 2220<b>pcre_exec()</b>, and <i>stringcount</i> is the number of substrings that were 2221captured by the match, including the substring that matched the entire regular 2222expression. This is the value returned by <b>pcre_exec()</b> if it is greater 2223than zero. If <b>pcre_exec()</b> returned zero, indicating that it ran out of 2224space in <i>ovector</i>, the value passed as <i>stringcount</i> should be the 2225number of elements in the vector divided by three. 2226</P> 2227<P> 2228The functions <b>pcre_copy_substring()</b> and <b>pcre_get_substring()</b> 2229extract a single substring, whose number is given as <i>stringnumber</i>. A 2230value of zero extracts the substring that matched the entire pattern, whereas 2231higher values extract the captured substrings. For <b>pcre_copy_substring()</b>, 2232the string is placed in <i>buffer</i>, whose length is given by 2233<i>buffersize</i>, while for <b>pcre_get_substring()</b> a new block of memory is 2234obtained via <b>pcre_malloc</b>, and its address is returned via 2235<i>stringptr</i>. The yield of the function is the length of the string, not 2236including the terminating zero, or one of these error codes: 2237<pre> 2238 PCRE_ERROR_NOMEMORY (-6) 2239</pre> 2240The buffer was too small for <b>pcre_copy_substring()</b>, or the attempt to get 2241memory failed for <b>pcre_get_substring()</b>. 2242<pre> 2243 PCRE_ERROR_NOSUBSTRING (-7) 2244</pre> 2245There is no substring whose number is <i>stringnumber</i>. 2246</P> 2247<P> 2248The <b>pcre_get_substring_list()</b> function extracts all available substrings 2249and builds a list of pointers to them. All this is done in a single block of 2250memory that is obtained via <b>pcre_malloc</b>. The address of the memory block 2251is returned via <i>listptr</i>, which is also the start of the list of string 2252pointers. The end of the list is marked by a NULL pointer. The yield of the 2253function is zero if all went well, or the error code 2254<pre> 2255 PCRE_ERROR_NOMEMORY (-6) 2256</pre> 2257if the attempt to get the memory block failed. 2258</P> 2259<P> 2260When any of these functions encounter a substring that is unset, which can 2261happen when capturing subpattern number <i>n+1</i> matches some part of the 2262subject, but subpattern <i>n</i> has not been used at all, they return an empty 2263string. This can be distinguished from a genuine zero-length substring by 2264inspecting the appropriate offset in <i>ovector</i>, which is negative for unset 2265substrings. 2266</P> 2267<P> 2268The two convenience functions <b>pcre_free_substring()</b> and 2269<b>pcre_free_substring_list()</b> can be used to free the memory returned by 2270a previous call of <b>pcre_get_substring()</b> or 2271<b>pcre_get_substring_list()</b>, respectively. They do nothing more than call 2272the function pointed to by <b>pcre_free</b>, which of course could be called 2273directly from a C program. However, PCRE is used in some situations where it is 2274linked via a special interface to another programming language that cannot use 2275<b>pcre_free</b> directly; it is for these cases that the functions are 2276provided. 2277</P> 2278<br><a name="SEC19" href="#TOC1">EXTRACTING CAPTURED SUBSTRINGS BY NAME</a><br> 2279<P> 2280<b>int pcre_get_stringnumber(const pcre *<i>code</i>,</b> 2281<b>const char *<i>name</i>);</b> 2282</P> 2283<P> 2284<b>int pcre_copy_named_substring(const pcre *<i>code</i>,</b> 2285<b>const char *<i>subject</i>, int *<i>ovector</i>,</b> 2286<b>int <i>stringcount</i>, const char *<i>stringname</i>,</b> 2287<b>char *<i>buffer</i>, int <i>buffersize</i>);</b> 2288</P> 2289<P> 2290<b>int pcre_get_named_substring(const pcre *<i>code</i>,</b> 2291<b>const char *<i>subject</i>, int *<i>ovector</i>,</b> 2292<b>int <i>stringcount</i>, const char *<i>stringname</i>,</b> 2293<b>const char **<i>stringptr</i>);</b> 2294</P> 2295<P> 2296To extract a substring by name, you first have to find associated number. 2297For example, for this pattern 2298<pre> 2299 (a+)b(?<xxx>\d+)... 2300</pre> 2301the number of the subpattern called "xxx" is 2. If the name is known to be 2302unique (PCRE_DUPNAMES was not set), you can find the number from the name by 2303calling <b>pcre_get_stringnumber()</b>. The first argument is the compiled 2304pattern, and the second is the name. The yield of the function is the 2305subpattern number, or PCRE_ERROR_NOSUBSTRING (-7) if there is no subpattern of 2306that name. 2307</P> 2308<P> 2309Given the number, you can extract the substring directly, or use one of the 2310functions described in the previous section. For convenience, there are also 2311two functions that do the whole job. 2312</P> 2313<P> 2314Most of the arguments of <b>pcre_copy_named_substring()</b> and 2315<b>pcre_get_named_substring()</b> are the same as those for the similarly named 2316functions that extract by number. As these are described in the previous 2317section, they are not re-described here. There are just two differences: 2318</P> 2319<P> 2320First, instead of a substring number, a substring name is given. Second, there 2321is an extra argument, given at the start, which is a pointer to the compiled 2322pattern. This is needed in order to gain access to the name-to-number 2323translation table. 2324</P> 2325<P> 2326These functions call <b>pcre_get_stringnumber()</b>, and if it succeeds, they 2327then call <b>pcre_copy_substring()</b> or <b>pcre_get_substring()</b>, as 2328appropriate. <b>NOTE:</b> If PCRE_DUPNAMES is set and there are duplicate names, 2329the behaviour may not be what you want (see the next section). 2330</P> 2331<P> 2332<b>Warning:</b> If the pattern uses the (?| feature to set up multiple 2333subpatterns with the same number, as described in the 2334<a href="pcrepattern.html#dupsubpatternnumber">section on duplicate subpattern numbers</a> 2335in the 2336<a href="pcrepattern.html"><b>pcrepattern</b></a> 2337page, you cannot use names to distinguish the different subpatterns, because 2338names are not included in the compiled code. The matching process uses only 2339numbers. For this reason, the use of different names for subpatterns of the 2340same number causes an error at compile time. 2341</P> 2342<br><a name="SEC20" href="#TOC1">DUPLICATE SUBPATTERN NAMES</a><br> 2343<P> 2344<b>int pcre_get_stringtable_entries(const pcre *<i>code</i>,</b> 2345<b>const char *<i>name</i>, char **<i>first</i>, char **<i>last</i>);</b> 2346</P> 2347<P> 2348When a pattern is compiled with the PCRE_DUPNAMES option, names for subpatterns 2349are not required to be unique. (Duplicate names are always allowed for 2350subpatterns with the same number, created by using the (?| feature. Indeed, if 2351such subpatterns are named, they are required to use the same names.) 2352</P> 2353<P> 2354Normally, patterns with duplicate names are such that in any one match, only 2355one of the named subpatterns participates. An example is shown in the 2356<a href="pcrepattern.html"><b>pcrepattern</b></a> 2357documentation. 2358</P> 2359<P> 2360When duplicates are present, <b>pcre_copy_named_substring()</b> and 2361<b>pcre_get_named_substring()</b> return the first substring corresponding to 2362the given name that is set. If none are set, PCRE_ERROR_NOSUBSTRING (-7) is 2363returned; no data is returned. The <b>pcre_get_stringnumber()</b> function 2364returns one of the numbers that are associated with the name, but it is not 2365defined which it is. 2366</P> 2367<P> 2368If you want to get full details of all captured substrings for a given name, 2369you must use the <b>pcre_get_stringtable_entries()</b> function. The first 2370argument is the compiled pattern, and the second is the name. The third and 2371fourth are pointers to variables which are updated by the function. After it 2372has run, they point to the first and last entries in the name-to-number table 2373for the given name. The function itself returns the length of each entry, or 2374PCRE_ERROR_NOSUBSTRING (-7) if there are none. The format of the table is 2375described above in the section entitled <i>Information about a pattern</i> 2376<a href="#infoaboutpattern">above.</a> 2377Given all the relevant entries for the name, you can extract each of their 2378numbers, and hence the captured data, if any. 2379</P> 2380<br><a name="SEC21" href="#TOC1">FINDING ALL POSSIBLE MATCHES</a><br> 2381<P> 2382The traditional matching function uses a similar algorithm to Perl, which stops 2383when it finds the first match, starting at a given point in the subject. If you 2384want to find all possible matches, or the longest possible match, consider 2385using the alternative matching function (see below) instead. If you cannot use 2386the alternative function, but still need to find all possible matches, you 2387can kludge it up by making use of the callout facility, which is described in 2388the 2389<a href="pcrecallout.html"><b>pcrecallout</b></a> 2390documentation. 2391</P> 2392<P> 2393What you have to do is to insert a callout right at the end of the pattern. 2394When your callout function is called, extract and save the current matched 2395substring. Then return 1, which forces <b>pcre_exec()</b> to backtrack and try 2396other alternatives. Ultimately, when it runs out of matches, <b>pcre_exec()</b> 2397will yield PCRE_ERROR_NOMATCH. 2398</P> 2399<br><a name="SEC22" href="#TOC1">OBTAINING AN ESTIMATE OF STACK USAGE</a><br> 2400<P> 2401Matching certain patterns using <b>pcre_exec()</b> can use a lot of process 2402stack, which in certain environments can be rather limited in size. Some users 2403find it helpful to have an estimate of the amount of stack that is used by 2404<b>pcre_exec()</b>, to help them set recursion limits, as described in the 2405<a href="pcrestack.html"><b>pcrestack</b></a> 2406documentation. The estimate that is output by <b>pcretest</b> when called with 2407the <b>-m</b> and <b>-C</b> options is obtained by calling <b>pcre_exec</b> with 2408the values NULL, NULL, NULL, -999, and -999 for its first five arguments. 2409</P> 2410<P> 2411Normally, if its first argument is NULL, <b>pcre_exec()</b> immediately returns 2412the negative error code PCRE_ERROR_NULL, but with this special combination of 2413arguments, it returns instead a negative number whose absolute value is the 2414approximate stack frame size in bytes. (A negative number is used so that it is 2415clear that no match has happened.) The value is approximate because in some 2416cases, recursive calls to <b>pcre_exec()</b> occur when there are one or two 2417additional variables on the stack. 2418</P> 2419<P> 2420If PCRE has been compiled to use the heap instead of the stack for recursion, 2421the value returned is the size of each block that is obtained from the heap. 2422<a name="dfamatch"></a></P> 2423<br><a name="SEC23" href="#TOC1">MATCHING A PATTERN: THE ALTERNATIVE FUNCTION</a><br> 2424<P> 2425<b>int pcre_dfa_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> 2426<b>const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b> 2427<b>int <i>options</i>, int *<i>ovector</i>, int <i>ovecsize</i>,</b> 2428<b>int *<i>workspace</i>, int <i>wscount</i>);</b> 2429</P> 2430<P> 2431The function <b>pcre_dfa_exec()</b> is called to match a subject string against 2432a compiled pattern, using a matching algorithm that scans the subject string 2433just once, and does not backtrack. This has different characteristics to the 2434normal algorithm, and is not compatible with Perl. Some of the features of PCRE 2435patterns are not supported. Nevertheless, there are times when this kind of 2436matching can be useful. For a discussion of the two matching algorithms, and a 2437list of features that <b>pcre_dfa_exec()</b> does not support, see the 2438<a href="pcrematching.html"><b>pcrematching</b></a> 2439documentation. 2440</P> 2441<P> 2442The arguments for the <b>pcre_dfa_exec()</b> function are the same as for 2443<b>pcre_exec()</b>, plus two extras. The <i>ovector</i> argument is used in a 2444different way, and this is described below. The other common arguments are used 2445in the same way as for <b>pcre_exec()</b>, so their description is not repeated 2446here. 2447</P> 2448<P> 2449The two additional arguments provide workspace for the function. The workspace 2450vector should contain at least 20 elements. It is used for keeping track of 2451multiple paths through the pattern tree. More workspace will be needed for 2452patterns and subjects where there are a lot of potential matches. 2453</P> 2454<P> 2455Here is an example of a simple call to <b>pcre_dfa_exec()</b>: 2456<pre> 2457 int rc; 2458 int ovector[10]; 2459 int wspace[20]; 2460 rc = pcre_dfa_exec( 2461 re, /* result of pcre_compile() */ 2462 NULL, /* we didn't study the pattern */ 2463 "some string", /* the subject string */ 2464 11, /* the length of the subject string */ 2465 0, /* start at offset 0 in the subject */ 2466 0, /* default options */ 2467 ovector, /* vector of integers for substring information */ 2468 10, /* number of elements (NOT size in bytes) */ 2469 wspace, /* working space vector */ 2470 20); /* number of elements (NOT size in bytes) */ 2471</PRE> 2472</P> 2473<br><b> 2474Option bits for <b>pcre_dfa_exec()</b> 2475</b><br> 2476<P> 2477The unused bits of the <i>options</i> argument for <b>pcre_dfa_exec()</b> must be 2478zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_<i>xxx</i>, 2479PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART, 2480PCRE_NO_UTF8_CHECK, PCRE_BSR_ANYCRLF, PCRE_BSR_UNICODE, PCRE_NO_START_OPTIMIZE, 2481PCRE_PARTIAL_HARD, PCRE_PARTIAL_SOFT, PCRE_DFA_SHORTEST, and PCRE_DFA_RESTART. 2482All but the last four of these are exactly the same as for <b>pcre_exec()</b>, 2483so their description is not repeated here. 2484<pre> 2485 PCRE_PARTIAL_HARD 2486 PCRE_PARTIAL_SOFT 2487</pre> 2488These have the same general effect as they do for <b>pcre_exec()</b>, but the 2489details are slightly different. When PCRE_PARTIAL_HARD is set for 2490<b>pcre_dfa_exec()</b>, it returns PCRE_ERROR_PARTIAL if the end of the subject 2491is reached and there is still at least one matching possibility that requires 2492additional characters. This happens even if some complete matches have also 2493been found. When PCRE_PARTIAL_SOFT is set, the return code PCRE_ERROR_NOMATCH 2494is converted into PCRE_ERROR_PARTIAL if the end of the subject is reached, 2495there have been no complete matches, but there is still at least one matching 2496possibility. The portion of the string that was inspected when the longest 2497partial match was found is set as the first matching string in both cases. 2498There is a more detailed discussion of partial and multi-segment matching, with 2499examples, in the 2500<a href="pcrepartial.html"><b>pcrepartial</b></a> 2501documentation. 2502<pre> 2503 PCRE_DFA_SHORTEST 2504</pre> 2505Setting the PCRE_DFA_SHORTEST option causes the matching algorithm to stop as 2506soon as it has found one match. Because of the way the alternative algorithm 2507works, this is necessarily the shortest possible match at the first possible 2508matching point in the subject string. 2509<pre> 2510 PCRE_DFA_RESTART 2511</pre> 2512When <b>pcre_dfa_exec()</b> returns a partial match, it is possible to call it 2513again, with additional subject characters, and have it continue with the same 2514match. The PCRE_DFA_RESTART option requests this action; when it is set, the 2515<i>workspace</i> and <i>wscount</i> options must reference the same vector as 2516before because data about the match so far is left in them after a partial 2517match. There is more discussion of this facility in the 2518<a href="pcrepartial.html"><b>pcrepartial</b></a> 2519documentation. 2520</P> 2521<br><b> 2522Successful returns from <b>pcre_dfa_exec()</b> 2523</b><br> 2524<P> 2525When <b>pcre_dfa_exec()</b> succeeds, it may have matched more than one 2526substring in the subject. Note, however, that all the matches from one run of 2527the function start at the same point in the subject. The shorter matches are 2528all initial substrings of the longer matches. For example, if the pattern 2529<pre> 2530 <.*> 2531</pre> 2532is matched against the string 2533<pre> 2534 This is <something> <something else> <something further> no more 2535</pre> 2536the three matched strings are 2537<pre> 2538 <something> 2539 <something> <something else> 2540 <something> <something else> <something further> 2541</pre> 2542On success, the yield of the function is a number greater than zero, which is 2543the number of matched substrings. The substrings themselves are returned in 2544<i>ovector</i>. Each string uses two elements; the first is the offset to the 2545start, and the second is the offset to the end. In fact, all the strings have 2546the same start offset. (Space could have been saved by giving this only once, 2547but it was decided to retain some compatibility with the way <b>pcre_exec()</b> 2548returns data, even though the meaning of the strings is different.) 2549</P> 2550<P> 2551The strings are returned in reverse order of length; that is, the longest 2552matching string is given first. If there were too many matches to fit into 2553<i>ovector</i>, the yield of the function is zero, and the vector is filled with 2554the longest matches. Unlike <b>pcre_exec()</b>, <b>pcre_dfa_exec()</b> can use 2555the entire <i>ovector</i> for returning matched strings. 2556</P> 2557<br><b> 2558Error returns from <b>pcre_dfa_exec()</b> 2559</b><br> 2560<P> 2561The <b>pcre_dfa_exec()</b> function returns a negative number when it fails. 2562Many of the errors are the same as for <b>pcre_exec()</b>, and these are 2563described 2564<a href="#errorlist">above.</a> 2565There are in addition the following errors that are specific to 2566<b>pcre_dfa_exec()</b>: 2567<pre> 2568 PCRE_ERROR_DFA_UITEM (-16) 2569</pre> 2570This return is given if <b>pcre_dfa_exec()</b> encounters an item in the pattern 2571that it does not support, for instance, the use of \C or a back reference. 2572<pre> 2573 PCRE_ERROR_DFA_UCOND (-17) 2574</pre> 2575This return is given if <b>pcre_dfa_exec()</b> encounters a condition item that 2576uses a back reference for the condition, or a test for recursion in a specific 2577group. These are not supported. 2578<pre> 2579 PCRE_ERROR_DFA_UMLIMIT (-18) 2580</pre> 2581This return is given if <b>pcre_dfa_exec()</b> is called with an <i>extra</i> 2582block that contains a setting of the <i>match_limit</i> or 2583<i>match_limit_recursion</i> fields. This is not supported (these fields are 2584meaningless for DFA matching). 2585<pre> 2586 PCRE_ERROR_DFA_WSSIZE (-19) 2587</pre> 2588This return is given if <b>pcre_dfa_exec()</b> runs out of space in the 2589<i>workspace</i> vector. 2590<pre> 2591 PCRE_ERROR_DFA_RECURSE (-20) 2592</pre> 2593When a recursive subpattern is processed, the matching function calls itself 2594recursively, using private vectors for <i>ovector</i> and <i>workspace</i>. This 2595error is given if the output vector is not large enough. This should be 2596extremely rare, as a vector of size 1000 is used. 2597<pre> 2598 PCRE_ERROR_DFA_BADRESTART (-30) 2599</pre> 2600When <b>pcre_dfa_exec()</b> is called with the <b>PCRE_DFA_RESTART</b> option, 2601some plausibility checks are made on the contents of the workspace, which 2602should contain data about the previous partial match. If any of these checks 2603fail, this error is given. 2604</P> 2605<br><a name="SEC24" href="#TOC1">SEE ALSO</a><br> 2606<P> 2607<b>pcre16</b>(3), <b>pcrebuild</b>(3), <b>pcrecallout</b>(3), <b>pcrecpp(3)</b>(3), 2608<b>pcrematching</b>(3), <b>pcrepartial</b>(3), <b>pcreposix</b>(3), 2609<b>pcreprecompile</b>(3), <b>pcresample</b>(3), <b>pcrestack</b>(3). 2610</P> 2611<br><a name="SEC25" href="#TOC1">AUTHOR</a><br> 2612<P> 2613Philip Hazel 2614<br> 2615University Computing Service 2616<br> 2617Cambridge CB2 3QH, England. 2618<br> 2619</P> 2620<br><a name="SEC26" href="#TOC1">REVISION</a><br> 2621<P> 2622Last updated: 17 June 2012 2623<br> 2624Copyright © 1997-2012 University of Cambridge. 2625<br> 2626<p> 2627Return to the <a href="index.html">PCRE index page</a>. 2628</p> 2629