embedaddon/pcre/doc/html/pcreapi.html - view

File: [ELWIX - Embedded LightWeight unIX -] / embedaddon / pcre / doc / html / pcreapi.html
Revision 1.1.1.5 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Sun Jun 15 19:46:05 2014 UTC (10 years, 9 months ago) by misho
Branches: pcre, MAIN
CVS tags: v8_34, HEAD

pcre 8.34

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