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