PageRenderTime 83ms CodeModel.GetById 3ms app.highlight 61ms RepoModel.GetById 0ms app.codeStats 1ms

/vendor/pcre/doc/html/pcreapi.html

http://github.com/feyeleanor/RubyGoLightly
HTML | 1985 lines | 1985 code | 0 blank | 0 comment | 0 complexity | 2a29757d96575a3e7260f91b4efec45a MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1<html>
   2<head>
   3<title>pcreapi specification</title>
   4</head>
   5<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB">
   6<h1>pcreapi man page</h1>
   7<p>
   8Return to the <a href="index.html">PCRE index page</a>.
   9</p>
  10<p>
  11This page is part of the PCRE HTML documentation. It was generated automatically
  12from the original man page. If there is any nonsense in it, please consult the
  13man page, in case the conversion went wrong.
  14<br>
  15<ul>
  16<li><a name="TOC1" href="#SEC1">PCRE NATIVE API</a>
  17<li><a name="TOC2" href="#SEC2">PCRE API OVERVIEW</a>
  18<li><a name="TOC3" href="#SEC3">NEWLINES</a>
  19<li><a name="TOC4" href="#SEC4">MULTITHREADING</a>
  20<li><a name="TOC5" href="#SEC5">SAVING PRECOMPILED PATTERNS FOR LATER USE</a>
  21<li><a name="TOC6" href="#SEC6">CHECKING BUILD-TIME OPTIONS</a>
  22<li><a name="TOC7" href="#SEC7">COMPILING A PATTERN</a>
  23<li><a name="TOC8" href="#SEC8">COMPILATION ERROR CODES</a>
  24<li><a name="TOC9" href="#SEC9">STUDYING A PATTERN</a>
  25<li><a name="TOC10" href="#SEC10">LOCALE SUPPORT</a>
  26<li><a name="TOC11" href="#SEC11">INFORMATION ABOUT A PATTERN</a>
  27<li><a name="TOC12" href="#SEC12">OBSOLETE INFO FUNCTION</a>
  28<li><a name="TOC13" href="#SEC13">REFERENCE COUNTS</a>
  29<li><a name="TOC14" href="#SEC14">MATCHING A PATTERN: THE TRADITIONAL FUNCTION</a>
  30<li><a name="TOC15" href="#SEC15">EXTRACTING CAPTURED SUBSTRINGS BY NUMBER</a>
  31<li><a name="TOC16" href="#SEC16">EXTRACTING CAPTURED SUBSTRINGS BY NAME</a>
  32<li><a name="TOC17" href="#SEC17">DUPLICATE SUBPATTERN NAMES</a>
  33<li><a name="TOC18" href="#SEC18">FINDING ALL POSSIBLE MATCHES</a>
  34<li><a name="TOC19" href="#SEC19">MATCHING A PATTERN: THE ALTERNATIVE FUNCTION</a>
  35<li><a name="TOC20" href="#SEC20">SEE ALSO</a>
  36<li><a name="TOC21" href="#SEC21">AUTHOR</a>
  37<li><a name="TOC22" href="#SEC22">REVISION</a>
  38</ul>
  39<br><a name="SEC1" href="#TOC1">PCRE NATIVE API</a><br>
  40<P>
  41<b>#include &#60;pcre.h&#62;</b>
  42</P>
  43<P>
  44<b>pcre *pcre_compile(const char *<i>pattern</i>, int <i>options</i>,</b>
  45<b>const char **<i>errptr</i>, int *<i>erroffset</i>,</b>
  46<b>const unsigned char *<i>tableptr</i>);</b>
  47</P>
  48<P>
  49<b>pcre *pcre_compile2(const char *<i>pattern</i>, int <i>options</i>,</b>
  50<b>int *<i>errorcodeptr</i>,</b>
  51<b>const char **<i>errptr</i>, int *<i>erroffset</i>,</b>
  52<b>const unsigned char *<i>tableptr</i>);</b>
  53</P>
  54<P>
  55<b>pcre_extra *pcre_study(const pcre *<i>code</i>, int <i>options</i>,</b>
  56<b>const char **<i>errptr</i>);</b>
  57</P>
  58<P>
  59<b>int pcre_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b>
  60<b>const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b>
  61<b>int <i>options</i>, int *<i>ovector</i>, int <i>ovecsize</i>);</b>
  62</P>
  63<P>
  64<b>int pcre_dfa_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b>
  65<b>const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b>
  66<b>int <i>options</i>, int *<i>ovector</i>, int <i>ovecsize</i>,</b>
  67<b>int *<i>workspace</i>, int <i>wscount</i>);</b>
  68</P>
  69<P>
  70<b>int pcre_copy_named_substring(const pcre *<i>code</i>,</b>
  71<b>const char *<i>subject</i>, int *<i>ovector</i>,</b>
  72<b>int <i>stringcount</i>, const char *<i>stringname</i>,</b>
  73<b>char *<i>buffer</i>, int <i>buffersize</i>);</b>
  74</P>
  75<P>
  76<b>int pcre_copy_substring(const char *<i>subject</i>, int *<i>ovector</i>,</b>
  77<b>int <i>stringcount</i>, int <i>stringnumber</i>, char *<i>buffer</i>,</b>
  78<b>int <i>buffersize</i>);</b>
  79</P>
  80<P>
  81<b>int pcre_get_named_substring(const pcre *<i>code</i>,</b>
  82<b>const char *<i>subject</i>, int *<i>ovector</i>,</b>
  83<b>int <i>stringcount</i>, const char *<i>stringname</i>,</b>
  84<b>const char **<i>stringptr</i>);</b>
  85</P>
  86<P>
  87<b>int pcre_get_stringnumber(const pcre *<i>code</i>,</b>
  88<b>const char *<i>name</i>);</b>
  89</P>
  90<P>
  91<b>int pcre_get_stringtable_entries(const pcre *<i>code</i>,</b>
  92<b>const char *<i>name</i>, char **<i>first</i>, char **<i>last</i>);</b>
  93</P>
  94<P>
  95<b>int pcre_get_substring(const char *<i>subject</i>, int *<i>ovector</i>,</b>
  96<b>int <i>stringcount</i>, int <i>stringnumber</i>,</b>
  97<b>const char **<i>stringptr</i>);</b>
  98</P>
  99<P>
 100<b>int pcre_get_substring_list(const char *<i>subject</i>,</b>
 101<b>int *<i>ovector</i>, int <i>stringcount</i>, const char ***<i>listptr</i>);</b>
 102</P>
 103<P>
 104<b>void pcre_free_substring(const char *<i>stringptr</i>);</b>
 105</P>
 106<P>
 107<b>void pcre_free_substring_list(const char **<i>stringptr</i>);</b>
 108</P>
 109<P>
 110<b>const unsigned char *pcre_maketables(void);</b>
 111</P>
 112<P>
 113<b>int pcre_fullinfo(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b>
 114<b>int <i>what</i>, void *<i>where</i>);</b>
 115</P>
 116<P>
 117<b>int pcre_info(const pcre *<i>code</i>, int *<i>optptr</i>, int</b>
 118<b>*<i>firstcharptr</i>);</b>
 119</P>
 120<P>
 121<b>int pcre_refcount(pcre *<i>code</i>, int <i>adjust</i>);</b>
 122</P>
 123<P>
 124<b>int pcre_config(int <i>what</i>, void *<i>where</i>);</b>
 125</P>
 126<P>
 127<b>char *pcre_version(void);</b>
 128</P>
 129<P>
 130<b>void *(*pcre_malloc)(size_t);</b>
 131</P>
 132<P>
 133<b>void (*pcre_free)(void *);</b>
 134</P>
 135<P>
 136<b>void *(*pcre_stack_malloc)(size_t);</b>
 137</P>
 138<P>
 139<b>void (*pcre_stack_free)(void *);</b>
 140</P>
 141<P>
 142<b>int (*pcre_callout)(pcre_callout_block *);</b>
 143</P>
 144<br><a name="SEC2" href="#TOC1">PCRE API OVERVIEW</a><br>
 145<P>
 146PCRE has its own native API, which is described in this document. There are
 147also some wrapper functions that correspond to the POSIX regular expression
 148API. These are described in the
 149<a href="pcreposix.html"><b>pcreposix</b></a>
 150documentation. Both of these APIs define a set of C function calls. A C++
 151wrapper is distributed with PCRE. It is documented in the
 152<a href="pcrecpp.html"><b>pcrecpp</b></a>
 153page.
 154</P>
 155<P>
 156The native API C function prototypes are defined in the header file
 157<b>pcre.h</b>, and on Unix systems the library itself is called <b>libpcre</b>.
 158It can normally be accessed by adding <b>-lpcre</b> to the command for linking
 159an application that uses PCRE. The header file defines the macros PCRE_MAJOR
 160and PCRE_MINOR to contain the major and minor release numbers for the library.
 161Applications can use these to include support for different releases of PCRE.
 162</P>
 163<P>
 164The functions <b>pcre_compile()</b>, <b>pcre_compile2()</b>, <b>pcre_study()</b>,
 165and <b>pcre_exec()</b> are used for compiling and matching regular expressions
 166in a Perl-compatible manner. A sample program that demonstrates the simplest
 167way of using them is provided in the file called <i>pcredemo.c</i> in the source
 168distribution. The
 169<a href="pcresample.html"><b>pcresample</b></a>
 170documentation describes how to compile and run it.
 171</P>
 172<P>
 173A second matching function, <b>pcre_dfa_exec()</b>, which is not
 174Perl-compatible, is also provided. This uses a different algorithm for the
 175matching. The alternative algorithm finds all possible matches (at a given
 176point in the subject), and scans the subject just once. However, this algorithm
 177does not return captured substrings. A description of the two matching
 178algorithms and their advantages and disadvantages is given in the
 179<a href="pcrematching.html"><b>pcrematching</b></a>
 180documentation.
 181</P>
 182<P>
 183In addition to the main compiling and matching functions, there are convenience
 184functions for extracting captured substrings from a subject string that is
 185matched by <b>pcre_exec()</b>. They are:
 186<pre>
 187  <b>pcre_copy_substring()</b>
 188  <b>pcre_copy_named_substring()</b>
 189  <b>pcre_get_substring()</b>
 190  <b>pcre_get_named_substring()</b>
 191  <b>pcre_get_substring_list()</b>
 192  <b>pcre_get_stringnumber()</b>
 193  <b>pcre_get_stringtable_entries()</b>
 194</pre>
 195<b>pcre_free_substring()</b> and <b>pcre_free_substring_list()</b> are also
 196provided, to free the memory used for extracted strings.
 197</P>
 198<P>
 199The function <b>pcre_maketables()</b> is used to build a set of character tables
 200in the current locale for passing to <b>pcre_compile()</b>, <b>pcre_exec()</b>,
 201or <b>pcre_dfa_exec()</b>. This is an optional facility that is provided for
 202specialist use. Most commonly, no special tables are passed, in which case
 203internal tables that are generated when PCRE is built are used.
 204</P>
 205<P>
 206The function <b>pcre_fullinfo()</b> is used to find out information about a
 207compiled pattern; <b>pcre_info()</b> is an obsolete version that returns only
 208some of the available information, but is retained for backwards compatibility.
 209The function <b>pcre_version()</b> returns a pointer to a string containing the
 210version of PCRE and its date of release.
 211</P>
 212<P>
 213The function <b>pcre_refcount()</b> maintains a reference count in a data block
 214containing a compiled pattern. This is provided for the benefit of
 215object-oriented applications.
 216</P>
 217<P>
 218The global variables <b>pcre_malloc</b> and <b>pcre_free</b> initially contain
 219the entry points of the standard <b>malloc()</b> and <b>free()</b> functions,
 220respectively. PCRE calls the memory management functions via these variables,
 221so a calling program can replace them if it wishes to intercept the calls. This
 222should be done before calling any PCRE functions.
 223</P>
 224<P>
 225The global variables <b>pcre_stack_malloc</b> and <b>pcre_stack_free</b> are also
 226indirections to memory management functions. These special functions are used
 227only when PCRE is compiled to use the heap for remembering data, instead of
 228recursive function calls, when running the <b>pcre_exec()</b> function. See the
 229<a href="pcrebuild.html"><b>pcrebuild</b></a>
 230documentation for details of how to do this. It is a non-standard way of
 231building PCRE, for use in environments that have limited stacks. Because of the
 232greater use of memory management, it runs more slowly. Separate functions are
 233provided so that special-purpose external code can be used for this case. When
 234used, these functions are always called in a stack-like manner (last obtained,
 235first freed), and always for memory blocks of the same size. There is a
 236discussion about PCRE's stack usage in the
 237<a href="pcrestack.html"><b>pcrestack</b></a>
 238documentation.
 239</P>
 240<P>
 241The global variable <b>pcre_callout</b> initially contains NULL. It can be set
 242by the caller to a "callout" function, which PCRE will then call at specified
 243points during a matching operation. Details are given in the
 244<a href="pcrecallout.html"><b>pcrecallout</b></a>
 245documentation.
 246<a name="newlines"></a></P>
 247<br><a name="SEC3" href="#TOC1">NEWLINES</a><br>
 248<P>
 249PCRE supports five different conventions for indicating line breaks in
 250strings: a single CR (carriage return) character, a single LF (linefeed)
 251character, the two-character sequence CRLF, any of the three preceding, or any
 252Unicode newline sequence. The Unicode newline sequences are the three just
 253mentioned, plus the single characters VT (vertical tab, U+000B), FF (formfeed,
 254U+000C), NEL (next line, U+0085), LS (line separator, U+2028), and PS
 255(paragraph separator, U+2029).
 256</P>
 257<P>
 258Each of the first three conventions is used by at least one operating system as
 259its standard newline sequence. When PCRE is built, a default can be specified.
 260The default default is LF, which is the Unix standard. When PCRE is run, the
 261default can be overridden, either when a pattern is compiled, or when it is
 262matched.
 263</P>
 264<P>
 265At compile time, the newline convention can be specified by the <i>options</i>
 266argument of <b>pcre_compile()</b>, or it can be specified by special text at the
 267start of the pattern itself; this overrides any other settings. See the
 268<a href="pcrepattern.html"><b>pcrepattern</b></a>
 269page for details of the special character sequences.
 270</P>
 271<P>
 272In the PCRE documentation the word "newline" is used to mean "the character or
 273pair of characters that indicate a line break". The choice of newline
 274convention affects the handling of the dot, circumflex, and dollar
 275metacharacters, the handling of #-comments in /x mode, and, when CRLF is a
 276recognized line ending sequence, the match position advancement for a
 277non-anchored pattern. There is more detail about this in the
 278<a href="#execoptions">section on <b>pcre_exec()</b> options</a>
 279below.
 280</P>
 281<P>
 282The choice of newline convention does not affect the interpretation of
 283the \n or \r escape sequences, nor does it affect what \R matches, which is
 284controlled in a similar way, but by separate options.
 285</P>
 286<br><a name="SEC4" href="#TOC1">MULTITHREADING</a><br>
 287<P>
 288The PCRE functions can be used in multi-threading applications, with the
 289proviso that the memory management functions pointed to by <b>pcre_malloc</b>,
 290<b>pcre_free</b>, <b>pcre_stack_malloc</b>, and <b>pcre_stack_free</b>, and the
 291callout function pointed to by <b>pcre_callout</b>, are shared by all threads.
 292</P>
 293<P>
 294The compiled form of a regular expression is not altered during matching, so
 295the same compiled pattern can safely be used by several threads at once.
 296</P>
 297<br><a name="SEC5" href="#TOC1">SAVING PRECOMPILED PATTERNS FOR LATER USE</a><br>
 298<P>
 299The compiled form of a regular expression can be saved and re-used at a later
 300time, possibly by a different program, and even on a host other than the one on
 301which it was compiled. Details are given in the
 302<a href="pcreprecompile.html"><b>pcreprecompile</b></a>
 303documentation. However, compiling a regular expression with one version of PCRE
 304for use with a different version is not guaranteed to work and may cause
 305crashes.
 306</P>
 307<br><a name="SEC6" href="#TOC1">CHECKING BUILD-TIME OPTIONS</a><br>
 308<P>
 309<b>int pcre_config(int <i>what</i>, void *<i>where</i>);</b>
 310</P>
 311<P>
 312The function <b>pcre_config()</b> makes it possible for a PCRE client to
 313discover which optional features have been compiled into the PCRE library. The
 314<a href="pcrebuild.html"><b>pcrebuild</b></a>
 315documentation has more details about these optional features.
 316</P>
 317<P>
 318The first argument for <b>pcre_config()</b> is an integer, specifying which
 319information is required; the second argument is a pointer to a variable into
 320which the information is placed. The following information is available:
 321<pre>
 322  PCRE_CONFIG_UTF8
 323</pre>
 324The output is an integer that is set to one if UTF-8 support is available;
 325otherwise it is set to zero.
 326<pre>
 327  PCRE_CONFIG_UNICODE_PROPERTIES
 328</pre>
 329The output is an integer that is set to one if support for Unicode character
 330properties is available; otherwise it is set to zero.
 331<pre>
 332  PCRE_CONFIG_NEWLINE
 333</pre>
 334The output is an integer whose value specifies the default character sequence
 335that is recognized as meaning "newline". The four values that are supported
 336are: 10 for LF, 13 for CR, 3338 for CRLF, -2 for ANYCRLF, and -1 for ANY. The
 337default should normally be the standard sequence for your operating system.
 338<pre>
 339  PCRE_CONFIG_BSR
 340</pre>
 341The output is an integer whose value indicates what character sequences the \R
 342escape sequence matches by default. A value of 0 means that \R matches any
 343Unicode line ending sequence; a value of 1 means that \R matches only CR, LF,
 344or CRLF. The default can be overridden when a pattern is compiled or matched.
 345<pre>
 346  PCRE_CONFIG_LINK_SIZE
 347</pre>
 348The output is an integer that contains the number of bytes used for internal
 349linkage in compiled regular expressions. The value is 2, 3, or 4. Larger values
 350allow larger regular expressions to be compiled, at the expense of slower
 351matching. The default value of 2 is sufficient for all but the most massive
 352patterns, since it allows the compiled pattern to be up to 64K in size.
 353<pre>
 354  PCRE_CONFIG_POSIX_MALLOC_THRESHOLD
 355</pre>
 356The output is an integer that contains the threshold above which the POSIX
 357interface uses <b>malloc()</b> for output vectors. Further details are given in
 358the
 359<a href="pcreposix.html"><b>pcreposix</b></a>
 360documentation.
 361<pre>
 362  PCRE_CONFIG_MATCH_LIMIT
 363</pre>
 364The output is an integer that gives the default limit for the number of
 365internal matching function calls in a <b>pcre_exec()</b> execution. Further
 366details are given with <b>pcre_exec()</b> below.
 367<pre>
 368  PCRE_CONFIG_MATCH_LIMIT_RECURSION
 369</pre>
 370The output is an integer that gives the default limit for the depth of
 371recursion when calling the internal matching function in a <b>pcre_exec()</b>
 372execution. Further details are given with <b>pcre_exec()</b> below.
 373<pre>
 374  PCRE_CONFIG_STACKRECURSE
 375</pre>
 376The output is an integer that is set to one if internal recursion when running
 377<b>pcre_exec()</b> is implemented by recursive function calls that use the stack
 378to remember their state. This is the usual way that PCRE is compiled. The
 379output is zero if PCRE was compiled to use blocks of data on the heap instead
 380of recursive function calls. In this case, <b>pcre_stack_malloc</b> and
 381<b>pcre_stack_free</b> are called to manage memory blocks on the heap, thus
 382avoiding the use of the stack.
 383</P>
 384<br><a name="SEC7" href="#TOC1">COMPILING A PATTERN</a><br>
 385<P>
 386<b>pcre *pcre_compile(const char *<i>pattern</i>, int <i>options</i>,</b>
 387<b>const char **<i>errptr</i>, int *<i>erroffset</i>,</b>
 388<b>const unsigned char *<i>tableptr</i>);</b>
 389<b>pcre *pcre_compile2(const char *<i>pattern</i>, int <i>options</i>,</b>
 390<b>int *<i>errorcodeptr</i>,</b>
 391<b>const char **<i>errptr</i>, int *<i>erroffset</i>,</b>
 392<b>const unsigned char *<i>tableptr</i>);</b>
 393</P>
 394<P>
 395Either of the functions <b>pcre_compile()</b> or <b>pcre_compile2()</b> can be
 396called to compile a pattern into an internal form. The only difference between
 397the two interfaces is that <b>pcre_compile2()</b> has an additional argument,
 398<i>errorcodeptr</i>, via which a numerical error code can be returned.
 399</P>
 400<P>
 401The pattern is a C string terminated by a binary zero, and is passed in the
 402<i>pattern</i> argument. A pointer to a single block of memory that is obtained
 403via <b>pcre_malloc</b> is returned. This contains the compiled code and related
 404data. The <b>pcre</b> type is defined for the returned block; this is a typedef
 405for a structure whose contents are not externally defined. It is up to the
 406caller to free the memory (via <b>pcre_free</b>) when it is no longer required.
 407</P>
 408<P>
 409Although the compiled code of a PCRE regex is relocatable, that is, it does not
 410depend on memory location, the complete <b>pcre</b> data block is not
 411fully relocatable, because it may contain a copy of the <i>tableptr</i>
 412argument, which is an address (see below).
 413</P>
 414<P>
 415The <i>options</i> argument contains various bit settings that affect the
 416compilation. It should be zero if no options are required. The available
 417options are described below. Some of them, in particular, those that are
 418compatible with Perl, can also be set and unset from within the pattern (see
 419the detailed description in the
 420<a href="pcrepattern.html"><b>pcrepattern</b></a>
 421documentation). For these options, the contents of the <i>options</i> argument
 422specifies their initial settings at the start of compilation and execution. The
 423PCRE_ANCHORED and PCRE_NEWLINE_<i>xxx</i> options can be set at the time of
 424matching as well as at compile time.
 425</P>
 426<P>
 427If <i>errptr</i> is NULL, <b>pcre_compile()</b> returns NULL immediately.
 428Otherwise, if compilation of a pattern fails, <b>pcre_compile()</b> returns
 429NULL, and sets the variable pointed to by <i>errptr</i> to point to a textual
 430error message. This is a static string that is part of the library. You must
 431not try to free it. The offset from the start of the pattern to the character
 432where the error was discovered is placed in the variable pointed to by
 433<i>erroffset</i>, which must not be NULL. If it is, an immediate error is given.
 434</P>
 435<P>
 436If <b>pcre_compile2()</b> is used instead of <b>pcre_compile()</b>, and the
 437<i>errorcodeptr</i> argument is not NULL, a non-zero error code number is
 438returned via this argument in the event of an error. This is in addition to the
 439textual error message. Error codes and messages are listed below.
 440</P>
 441<P>
 442If the final argument, <i>tableptr</i>, is NULL, PCRE uses a default set of
 443character tables that are built when PCRE is compiled, using the default C
 444locale. Otherwise, <i>tableptr</i> must be an address that is the result of a
 445call to <b>pcre_maketables()</b>. This value is stored with the compiled
 446pattern, and used again by <b>pcre_exec()</b>, unless another table pointer is
 447passed to it. For more discussion, see the section on locale support below.
 448</P>
 449<P>
 450This code fragment shows a typical straightforward call to <b>pcre_compile()</b>:
 451<pre>
 452  pcre *re;
 453  const char *error;
 454  int erroffset;
 455  re = pcre_compile(
 456    "^A.*Z",          /* the pattern */
 457    0,                /* default options */
 458    &error,           /* for error message */
 459    &erroffset,       /* for error offset */
 460    NULL);            /* use default character tables */
 461</pre>
 462The following names for option bits are defined in the <b>pcre.h</b> header
 463file:
 464<pre>
 465  PCRE_ANCHORED
 466</pre>
 467If this bit is set, the pattern is forced to be "anchored", that is, it is
 468constrained to match only at the first matching point in the string that is
 469being searched (the "subject string"). This effect can also be achieved by
 470appropriate constructs in the pattern itself, which is the only way to do it in
 471Perl.
 472<pre>
 473  PCRE_AUTO_CALLOUT
 474</pre>
 475If this bit is set, <b>pcre_compile()</b> automatically inserts callout items,
 476all with number 255, before each pattern item. For discussion of the callout
 477facility, see the
 478<a href="pcrecallout.html"><b>pcrecallout</b></a>
 479documentation.
 480<pre>
 481  PCRE_BSR_ANYCRLF
 482  PCRE_BSR_UNICODE
 483</pre>
 484These options (which are mutually exclusive) control what the \R escape
 485sequence matches. The choice is either to match only CR, LF, or CRLF, or to
 486match any Unicode newline sequence. The default is specified when PCRE is
 487built. It can be overridden from within the pattern, or by setting an option
 488when a compiled pattern is matched.
 489<pre>
 490  PCRE_CASELESS
 491</pre>
 492If this bit is set, letters in the pattern match both upper and lower case
 493letters. It is equivalent to Perl's /i option, and it can be changed within a
 494pattern by a (?i) option setting. In UTF-8 mode, PCRE always understands the
 495concept of case for characters whose values are less than 128, so caseless
 496matching is always possible. For characters with higher values, the concept of
 497case is supported if PCRE is compiled with Unicode property support, but not
 498otherwise. If you want to use caseless matching for characters 128 and above,
 499you must ensure that PCRE is compiled with Unicode property support as well as
 500with UTF-8 support.
 501<pre>
 502  PCRE_DOLLAR_ENDONLY
 503</pre>
 504If this bit is set, a dollar metacharacter in the pattern matches only at the
 505end of the subject string. Without this option, a dollar also matches
 506immediately before a newline at the end of the string (but not before any other
 507newlines). The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is set.
 508There is no equivalent to this option in Perl, and no way to set it within a
 509pattern.
 510<pre>
 511  PCRE_DOTALL
 512</pre>
 513If this bit is set, a dot metacharater in the pattern matches all characters,
 514including those that indicate newline. Without it, a dot does not match when
 515the current position is at a newline. This option is equivalent to Perl's /s
 516option, and it can be changed within a pattern by a (?s) option setting. A
 517negative class such as [^a] always matches newline characters, independent of
 518the setting of this option.
 519<pre>
 520  PCRE_DUPNAMES
 521</pre>
 522If this bit is set, names used to identify capturing subpatterns need not be
 523unique. This can be helpful for certain types of pattern when it is known that
 524only one instance of the named subpattern can ever be matched. There are more
 525details of named subpatterns below; see also the
 526<a href="pcrepattern.html"><b>pcrepattern</b></a>
 527documentation.
 528<pre>
 529  PCRE_EXTENDED
 530</pre>
 531If this bit is set, whitespace data characters in the pattern are totally
 532ignored except when escaped or inside a character class. Whitespace does not
 533include the VT character (code 11). In addition, characters between an
 534unescaped # outside a character class and the next newline, inclusive, are also
 535ignored. This is equivalent to Perl's /x option, and it can be changed within a
 536pattern by a (?x) option setting.
 537</P>
 538<P>
 539This option makes it possible to include comments inside complicated patterns.
 540Note, however, that this applies only to data characters. Whitespace characters
 541may never appear within special character sequences in a pattern, for example
 542within the sequence (?( which introduces a conditional subpattern.
 543<pre>
 544  PCRE_EXTRA
 545</pre>
 546This option was invented in order to turn on additional functionality of PCRE
 547that is incompatible with Perl, but it is currently of very little use. When
 548set, any backslash in a pattern that is followed by a letter that has no
 549special meaning causes an error, thus reserving these combinations for future
 550expansion. By default, as in Perl, a backslash followed by a letter with no
 551special meaning is treated as a literal. (Perl can, however, be persuaded to
 552give a warning for this.) There are at present no other features controlled by
 553this option. It can also be set by a (?X) option setting within a pattern.
 554<pre>
 555  PCRE_FIRSTLINE
 556</pre>
 557If this option is set, an unanchored pattern is required to match before or at
 558the first newline in the subject string, though the matched text may continue
 559over the newline.
 560<pre>
 561  PCRE_JAVASCRIPT_COMPAT
 562</pre>
 563If this option is set, PCRE's behaviour is changed in some ways so that it is
 564compatible with JavaScript rather than Perl. The changes are as follows:
 565</P>
 566<P>
 567(1) A lone closing square bracket in a pattern causes a compile-time error,
 568because this is illegal in JavaScript (by default it is treated as a data
 569character). Thus, the pattern AB]CD becomes illegal when this option is set.
 570</P>
 571<P>
 572(2) At run time, a back reference to an unset subpattern group matches an empty
 573string (by default this causes the current matching alternative to fail). A
 574pattern such as (\1)(a) succeeds when this option is set (assuming it can find
 575an "a" in the subject), whereas it fails by default, for Perl compatibility.
 576<pre>
 577  PCRE_MULTILINE
 578</pre>
 579By default, PCRE treats the subject string as consisting of a single line of
 580characters (even if it actually contains newlines). The "start of line"
 581metacharacter (^) matches only at the start of the string, while the "end of
 582line" metacharacter ($) matches only at the end of the string, or before a
 583terminating newline (unless PCRE_DOLLAR_ENDONLY is set). This is the same as
 584Perl.
 585</P>
 586<P>
 587When PCRE_MULTILINE it is set, the "start of line" and "end of line" constructs
 588match immediately following or immediately before internal newlines in the
 589subject string, respectively, as well as at the very start and end. This is
 590equivalent to Perl's /m option, and it can be changed within a pattern by a
 591(?m) option setting. If there are no newlines in a subject string, or no
 592occurrences of ^ or $ in a pattern, setting PCRE_MULTILINE has no effect.
 593<pre>
 594  PCRE_NEWLINE_CR
 595  PCRE_NEWLINE_LF
 596  PCRE_NEWLINE_CRLF
 597  PCRE_NEWLINE_ANYCRLF
 598  PCRE_NEWLINE_ANY
 599</pre>
 600These options override the default newline definition that was chosen when PCRE
 601was built. Setting the first or the second specifies that a newline is
 602indicated by a single character (CR or LF, respectively). Setting
 603PCRE_NEWLINE_CRLF specifies that a newline is indicated by the two-character
 604CRLF sequence. Setting PCRE_NEWLINE_ANYCRLF specifies that any of the three
 605preceding sequences should be recognized. Setting PCRE_NEWLINE_ANY specifies
 606that any Unicode newline sequence should be recognized. The Unicode newline
 607sequences are the three just mentioned, plus the single characters VT (vertical
 608tab, U+000B), FF (formfeed, U+000C), NEL (next line, U+0085), LS (line
 609separator, U+2028), and PS (paragraph separator, U+2029). The last two are
 610recognized only in UTF-8 mode.
 611</P>
 612<P>
 613The newline setting in the options word uses three bits that are treated
 614as a number, giving eight possibilities. Currently only six are used (default
 615plus the five values above). This means that if you set more than one newline
 616option, the combination may or may not be sensible. For example,
 617PCRE_NEWLINE_CR with PCRE_NEWLINE_LF is equivalent to PCRE_NEWLINE_CRLF, but
 618other combinations may yield unused numbers and cause an error.
 619</P>
 620<P>
 621The only time that a line break is specially recognized when compiling a
 622pattern is if PCRE_EXTENDED is set, and an unescaped # outside a character
 623class is encountered. This indicates a comment that lasts until after the next
 624line break sequence. In other circumstances, line break sequences are treated
 625as literal data, except that in PCRE_EXTENDED mode, both CR and LF are treated
 626as whitespace characters and are therefore ignored.
 627</P>
 628<P>
 629The newline option that is set at compile time becomes the default that is used
 630for <b>pcre_exec()</b> and <b>pcre_dfa_exec()</b>, but it can be overridden.
 631<pre>
 632  PCRE_NO_AUTO_CAPTURE
 633</pre>
 634If this option is set, it disables the use of numbered capturing parentheses in
 635the pattern. Any opening parenthesis that is not followed by ? behaves as if it
 636were followed by ?: but named parentheses can still be used for capturing (and
 637they acquire numbers in the usual way). There is no equivalent of this option
 638in Perl.
 639<pre>
 640  PCRE_UNGREEDY
 641</pre>
 642This option inverts the "greediness" of the quantifiers so that they are not
 643greedy by default, but become greedy if followed by "?". It is not compatible
 644with Perl. It can also be set by a (?U) option setting within the pattern.
 645<pre>
 646  PCRE_UTF8
 647</pre>
 648This option causes PCRE to regard both the pattern and the subject as strings
 649of UTF-8 characters instead of single-byte character strings. However, it is
 650available only when PCRE is built to include UTF-8 support. If not, the use
 651of this option provokes an error. Details of how this option changes the
 652behaviour of PCRE are given in the
 653<a href="pcre.html#utf8support">section on UTF-8 support</a>
 654in the main
 655<a href="pcre.html"><b>pcre</b></a>
 656page.
 657<pre>
 658  PCRE_NO_UTF8_CHECK
 659</pre>
 660When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string is
 661automatically checked. There is a discussion about the
 662<a href="pcre.html#utf8strings">validity of UTF-8 strings</a>
 663in the main
 664<a href="pcre.html"><b>pcre</b></a>
 665page. If an invalid UTF-8 sequence of bytes is found, <b>pcre_compile()</b>
 666returns an error. If you already know that your pattern is valid, and you want
 667to skip this check for performance reasons, you can set the PCRE_NO_UTF8_CHECK
 668option. When it is set, the effect of passing an invalid UTF-8 string as a
 669pattern is undefined. It may cause your program to crash. Note that this option
 670can also be passed to <b>pcre_exec()</b> and <b>pcre_dfa_exec()</b>, to suppress
 671the UTF-8 validity checking of subject strings.
 672</P>
 673<br><a name="SEC8" href="#TOC1">COMPILATION ERROR CODES</a><br>
 674<P>
 675The following table lists the error codes than may be returned by
 676<b>pcre_compile2()</b>, along with the error messages that may be returned by
 677both compiling functions. As PCRE has developed, some error codes have fallen
 678out of use. To avoid confusion, they have not been re-used.
 679<pre>
 680   0  no error
 681   1  \ at end of pattern
 682   2  \c at end of pattern
 683   3  unrecognized character follows \
 684   4  numbers out of order in {} quantifier
 685   5  number too big in {} quantifier
 686   6  missing terminating ] for character class
 687   7  invalid escape sequence in character class
 688   8  range out of order in character class
 689   9  nothing to repeat
 690  10  [this code is not in use]
 691  11  internal error: unexpected repeat
 692  12  unrecognized character after (? or (?-
 693  13  POSIX named classes are supported only within a class
 694  14  missing )
 695  15  reference to non-existent subpattern
 696  16  erroffset passed as NULL
 697  17  unknown option bit(s) set
 698  18  missing ) after comment
 699  19  [this code is not in use]
 700  20  regular expression is too large
 701  21  failed to get memory
 702  22  unmatched parentheses
 703  23  internal error: code overflow
 704  24  unrecognized character after (?&#60;
 705  25  lookbehind assertion is not fixed length
 706  26  malformed number or name after (?(
 707  27  conditional group contains more than two branches
 708  28  assertion expected after (?(
 709  29  (?R or (?[+-]digits must be followed by )
 710  30  unknown POSIX class name
 711  31  POSIX collating elements are not supported
 712  32  this version of PCRE is not compiled with PCRE_UTF8 support
 713  33  [this code is not in use]
 714  34  character value in \x{...} sequence is too large
 715  35  invalid condition (?(0)
 716  36  \C not allowed in lookbehind assertion
 717  37  PCRE does not support \L, \l, \N, \U, or \u
 718  38  number after (?C is &#62; 255
 719  39  closing ) for (?C expected
 720  40  recursive call could loop indefinitely
 721  41  unrecognized character after (?P
 722  42  syntax error in subpattern name (missing terminator)
 723  43  two named subpatterns have the same name
 724  44  invalid UTF-8 string
 725  45  support for \P, \p, and \X has not been compiled
 726  46  malformed \P or \p sequence
 727  47  unknown property name after \P or \p
 728  48  subpattern name is too long (maximum 32 characters)
 729  49  too many named subpatterns (maximum 10000)
 730  50  [this code is not in use]
 731  51  octal value is greater than \377 (not in UTF-8 mode)
 732  52  internal error: overran compiling workspace
 733  53  internal error: previously-checked referenced subpattern not found
 734  54  DEFINE group contains more than one branch
 735  55  repeating a DEFINE group is not allowed
 736  56  inconsistent NEWLINE options
 737  57  \g is not followed by a braced, angle-bracketed, or quoted
 738        name/number or by a plain number
 739  58  a numbered reference must not be zero
 740  59  (*VERB) with an argument is not supported
 741  60  (*VERB) not recognized
 742  61  number is too big
 743  62  subpattern name expected
 744  63  digit expected after (?+
 745  64  ] is an invalid data character in JavaScript compatibility mode
 746</pre>
 747The numbers 32 and 10000 in errors 48 and 49 are defaults; different values may
 748be used if the limits were changed when PCRE was built.
 749</P>
 750<br><a name="SEC9" href="#TOC1">STUDYING A PATTERN</a><br>
 751<P>
 752<b>pcre_extra *pcre_study(const pcre *<i>code</i>, int <i>options</i></b>
 753<b>const char **<i>errptr</i>);</b>
 754</P>
 755<P>
 756If a compiled pattern is going to be used several times, it is worth spending
 757more time analyzing it in order to speed up the time taken for matching. The
 758function <b>pcre_study()</b> takes a pointer to a compiled pattern as its first
 759argument. If studying the pattern produces additional information that will
 760help speed up matching, <b>pcre_study()</b> returns a pointer to a
 761<b>pcre_extra</b> block, in which the <i>study_data</i> field points to the
 762results of the study.
 763</P>
 764<P>
 765The returned value from <b>pcre_study()</b> can be passed directly to
 766<b>pcre_exec()</b>. However, a <b>pcre_extra</b> block also contains other
 767fields that can be set by the caller before the block is passed; these are
 768described
 769<a href="#extradata">below</a>
 770in the section on matching a pattern.
 771</P>
 772<P>
 773If studying the pattern does not produce any additional information
 774<b>pcre_study()</b> returns NULL. In that circumstance, if the calling program
 775wants to pass any of the other fields to <b>pcre_exec()</b>, it must set up its
 776own <b>pcre_extra</b> block.
 777</P>
 778<P>
 779The second argument of <b>pcre_study()</b> contains option bits. At present, no
 780options are defined, and this argument should always be zero.
 781</P>
 782<P>
 783The third argument for <b>pcre_study()</b> is a pointer for an error message. If
 784studying succeeds (even if no data is returned), the variable it points to is
 785set to NULL. Otherwise it is set to point to a textual error message. This is a
 786static string that is part of the library. You must not try to free it. You
 787should test the error pointer for NULL after calling <b>pcre_study()</b>, to be
 788sure that it has run successfully.
 789</P>
 790<P>
 791This is a typical call to <b>pcre_study</b>():
 792<pre>
 793  pcre_extra *pe;
 794  pe = pcre_study(
 795    re,             /* result of pcre_compile() */
 796    0,              /* no options exist */
 797    &error);        /* set to NULL or points to a message */
 798</pre>
 799At present, studying a pattern is useful only for non-anchored patterns that do
 800not have a single fixed starting character. A bitmap of possible starting
 801bytes is created.
 802<a name="localesupport"></a></P>
 803<br><a name="SEC10" href="#TOC1">LOCALE SUPPORT</a><br>
 804<P>
 805PCRE handles caseless matching, and determines whether characters are letters,
 806digits, or whatever, by reference to a set of tables, indexed by character
 807value. When running in UTF-8 mode, this applies only to characters with codes
 808less than 128. Higher-valued codes never match escapes such as \w or \d, but
 809can be tested with \p if PCRE is built with Unicode character property
 810support. The use of locales with Unicode is discouraged. If you are handling
 811characters with codes greater than 128, you should either use UTF-8 and
 812Unicode, or use locales, but not try to mix the two.
 813</P>
 814<P>
 815PCRE contains an internal set of tables that are used when the final argument
 816of <b>pcre_compile()</b> is NULL. These are sufficient for many applications.
 817Normally, the internal tables recognize only ASCII characters. However, when
 818PCRE is built, it is possible to cause the internal tables to be rebuilt in the
 819default "C" locale of the local system, which may cause them to be different.
 820</P>
 821<P>
 822The internal tables can always be overridden by tables supplied by the
 823application that calls PCRE. These may be created in a different locale from
 824the default. As more and more applications change to using Unicode, the need
 825for this locale support is expected to die away.
 826</P>
 827<P>
 828External tables are built by calling the <b>pcre_maketables()</b> function,
 829which has no arguments, in the relevant locale. The result can then be passed
 830to <b>pcre_compile()</b> or <b>pcre_exec()</b> as often as necessary. For
 831example, to build and use tables that are appropriate for the French locale
 832(where accented characters with values greater than 128 are treated as letters),
 833the following code could be used:
 834<pre>
 835  setlocale(LC_CTYPE, "fr_FR");
 836  tables = pcre_maketables();
 837  re = pcre_compile(..., tables);
 838</pre>
 839The locale name "fr_FR" is used on Linux and other Unix-like systems; if you
 840are using Windows, the name for the French locale is "french".
 841</P>
 842<P>
 843When <b>pcre_maketables()</b> runs, the tables are built in memory that is
 844obtained via <b>pcre_malloc</b>. It is the caller's responsibility to ensure
 845that the memory containing the tables remains available for as long as it is
 846needed.
 847</P>
 848<P>
 849The pointer that is passed to <b>pcre_compile()</b> is saved with the compiled
 850pattern, and the same tables are used via this pointer by <b>pcre_study()</b>
 851and normally also by <b>pcre_exec()</b>. Thus, by default, for any single
 852pattern, compilation, studying and matching all happen in the same locale, but
 853different patterns can be compiled in different locales.
 854</P>
 855<P>
 856It is possible to pass a table pointer or NULL (indicating the use of the
 857internal tables) to <b>pcre_exec()</b>. Although not intended for this purpose,
 858this facility could be used to match a pattern in a different locale from the
 859one in which it was compiled. Passing table pointers at run time is discussed
 860below in the section on matching a pattern.
 861</P>
 862<br><a name="SEC11" href="#TOC1">INFORMATION ABOUT A PATTERN</a><br>
 863<P>
 864<b>int pcre_fullinfo(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b>
 865<b>int <i>what</i>, void *<i>where</i>);</b>
 866</P>
 867<P>
 868The <b>pcre_fullinfo()</b> function returns information about a compiled
 869pattern. It replaces the obsolete <b>pcre_info()</b> function, which is
 870nevertheless retained for backwards compability (and is documented below).
 871</P>
 872<P>
 873The first argument for <b>pcre_fullinfo()</b> is a pointer to the compiled
 874pattern. The second argument is the result of <b>pcre_study()</b>, or NULL if
 875the pattern was not studied. The third argument specifies which piece of
 876information is required, and the fourth argument is a pointer to a variable
 877to receive the data. The yield of the function is zero for success, or one of
 878the following negative numbers:
 879<pre>
 880  PCRE_ERROR_NULL       the argument <i>code</i> was NULL
 881                        the argument <i>where</i> was NULL
 882  PCRE_ERROR_BADMAGIC   the "magic number" was not found
 883  PCRE_ERROR_BADOPTION  the value of <i>what</i> was invalid
 884</pre>
 885The "magic number" is placed at the start of each compiled pattern as an simple
 886check against passing an arbitrary memory pointer. Here is a typical call of
 887<b>pcre_fullinfo()</b>, to obtain the length of the compiled pattern:
 888<pre>
 889  int rc;
 890  size_t length;
 891  rc = pcre_fullinfo(
 892    re,               /* result of pcre_compile() */
 893    pe,               /* result of pcre_study(), or NULL */
 894    PCRE_INFO_SIZE,   /* what is required */
 895    &length);         /* where to put the data */
 896</pre>
 897The possible values for the third argument are defined in <b>pcre.h</b>, and are
 898as follows:
 899<pre>
 900  PCRE_INFO_BACKREFMAX
 901</pre>
 902Return the number of the highest back reference in the pattern. The fourth
 903argument should point to an <b>int</b> variable. Zero is returned if there are
 904no back references.
 905<pre>
 906  PCRE_INFO_CAPTURECOUNT
 907</pre>
 908Return the number of capturing subpatterns in the pattern. The fourth argument
 909should point to an <b>int</b> variable.
 910<pre>
 911  PCRE_INFO_DEFAULT_TABLES
 912</pre>
 913Return a pointer to the internal default character tables within PCRE. The
 914fourth argument should point to an <b>unsigned char *</b> variable. This
 915information call is provided for internal use by the <b>pcre_study()</b>
 916function. External callers can cause PCRE to use its internal tables by passing
 917a NULL table pointer.
 918<pre>
 919  PCRE_INFO_FIRSTBYTE
 920</pre>
 921Return information about the first byte of any matched string, for a
 922non-anchored pattern. The fourth argument should point to an <b>int</b>
 923variable. (This option used to be called PCRE_INFO_FIRSTCHAR; the old name is
 924still recognized for backwards compatibility.)
 925</P>
 926<P>
 927If there is a fixed first byte, for example, from a pattern such as
 928(cat|cow|coyote), its value is returned. Otherwise, if either
 929<br>
 930<br>
 931(a) the pattern was compiled with the PCRE_MULTILINE option, and every branch
 932starts with "^", or
 933<br>
 934<br>
 935(b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not set
 936(if it were set, the pattern would be anchored),
 937<br>
 938<br>
 939-1 is returned, indicating that the pattern matches only at the start of a
 940subject string or after any newline within the string. Otherwise -2 is
 941returned. For anchored patterns, -2 is returned.
 942<pre>
 943  PCRE_INFO_FIRSTTABLE
 944</pre>
 945If the pattern was studied, and this resulted in the construction of a 256-bit
 946table indicating a fixed set of bytes for the first byte in any matching
 947string, a pointer to the table is returned. Otherwise NULL is returned. The
 948fourth argument should point to an <b>unsigned char *</b> variable.
 949<pre>
 950  PCRE_INFO_HASCRORLF
 951</pre>
 952Return 1 if the pattern contains any explicit matches for CR or LF characters,
 953otherwise 0. The fourth argument should point to an <b>int</b> variable. An
 954explicit match is either a literal CR or LF character, or \r or \n.
 955<pre>
 956  PCRE_INFO_JCHANGED
 957</pre>
 958Return 1 if the (?J) or (?-J) option setting is used in the pattern, otherwise
 9590. The fourth argument should point to an <b>int</b> variable. (?J) and
 960(?-J) set and unset the local PCRE_DUPNAMES option, respectively.
 961<pre>
 962  PCRE_INFO_LASTLITERAL
 963</pre>
 964Return the value of the rightmost literal byte that must exist in any matched
 965string, other than at its start, if such a byte has been recorded. The fourth
 966argument should point to an <b>int</b> variable. If there is no such byte, -1 is
 967returned. For anchored patterns, a last literal byte is recorded only if it
 968follows something of variable length. For example, for the pattern
 969/^a\d+z\d+/ the returned value is "z", but for /^a\dz\d/ the returned value
 970is -1.
 971<pre>
 972  PCRE_INFO_NAMECOUNT
 973  PCRE_INFO_NAMEENTRYSIZE
 974  PCRE_INFO_NAMETABLE
 975</pre>
 976PCRE supports the use of named as well as numbered capturing parentheses. The
 977names are just an additional way of identifying the parentheses, which still
 978acquire numbers. Several convenience functions such as
 979<b>pcre_get_named_substring()</b> are provided for extracting captured
 980substrings by name. It is also possible to extract the data directly, by first
 981converting the name to a number in order to access the correct pointers in the
 982output vector (described with <b>pcre_exec()</b> below). To do the conversion,
 983you need to use the name-to-number map, which is described by these three
 984values.
 985</P>
 986<P>
 987The map consists of a number of fixed-size entries. PCRE_INFO_NAMECOUNT gives
 988the number of entries, and PCRE_INFO_NAMEENTRYSIZE gives the size of each
 989entry; both of these return an <b>int</b> value. The entry size depends on the
 990length of the longest name. PCRE_INFO_NAMETABLE returns a pointer to the first
 991entry of the table (a pointer to <b>char</b>). The first two bytes of each entry
 992are the number of the capturing parenthesis, most significant byte first. The
 993rest of the entry is the corresponding name, zero terminated. The names are in
 994alphabetical order. When PCRE_DUPNAMES is set, duplicate names are in order of
 995their parentheses numbers. For example, consider the following pattern (assume
 996PCRE_EXTENDED is set, so white space - including newlines - is ignored):
 997<pre>
 998  (?&#60;date&#62; (?&#60;year&#62;(\d\d)?\d\d) - (?&#60;month&#62;\d\d) - (?&#60;day&#62;\d\d) )
 999</pre>
1000There are four named subpatterns, so the table has four entries, and each entry
1001in the table is eight bytes long. The table is as follows, with non-printing
1002bytes shows in hexadecimal, and undefined bytes shown as ??:
1003<pre>
1004  00 01 d  a  t  e  00 ??
1005  00 05 d  a  y  00 ?? ??
1006  00 04 m  o  n  t  h  00
1007  00 02 y  e  a  r  00 ??
1008</pre>
1009When writing code to extract data from named subpatterns using the
1010name-to-number map, remember that the length of the entries is likely to be
1011different for each compiled pattern.
1012<pre>
1013  PCRE_INFO_OKPARTIAL
1014</pre>
1015Return 1 if the pattern can be used for partial matching, otherwise 0. The
1016fourth argument should point to an <b>int</b> variable. The
1017<a href="pcrepartial.html"><b>pcrepartial</b></a>
1018documentation lists the restrictions that apply to patterns when partial
1019matching is used.
1020<pre>
1021  PCRE_INFO_OPTIONS
1022</pre>
1023Return a copy of the options with which the pattern was compiled. The fourth
1024argument should point to an <b>unsigned long int</b> variable. These option bits
1025are those specified in the call to <b>pcre_compile()</b>, modified by any
1026top-level option settings at the start of the pattern itself. In other words,
1027they are the options that will be in force when matching starts. For example,
1028if the pattern /(?im)abc(?-i)d/ is compiled with the PCRE_EXTENDED option, the
1029result is PCRE_CASELESS, PCRE_MULTILINE, and PCRE_EXTENDED.
1030</P>
1031<P>
1032A pattern is automatically anchored by PCRE if all of its top-level
1033alternatives begin with one of the following:
1034<pre>
1035  ^     unless PCRE_MULTILINE is set
1036  \A    always
1037  \G    always
1038  .*    if PCRE_DOTALL is set and there are no back references to the subpattern in which .* appears
1039</pre>
1040For such patterns, the PCRE_ANCHORED bit is set in the options returned by
1041<b>pcre_fullinfo()</b>.
1042<pre>
1043  PCRE_INFO_SIZE
1044</pre>
1045Return the size of the compiled pattern, that is, the value that was passed as
1046the argument to <b>pcre_malloc()</b> when PCRE was getting memory in which to
1047place the compiled data. The fourth argument should point to a <b>size_t</b>
1048variable.
1049<pre>
1050  PCRE_INFO_STUDYSIZE
1051</pre>
1052Return the size of the data block pointed to by the <i>study_data</i> field in
1053a <b>pcre_extra</b> block. That is, it is the value that was passed to
1054<b>pcre_malloc()</b> when PCRE was getting memory into which to place the data
1055created by <b>pcre_study()</b>. The fourth argument should point to a
1056<b>size_t</b> variable.
1057</P>
1058<br><a name="SEC12" href="#TOC1">OBSOLETE INFO FUNCTION</a><br>
1059<P>
1060<b>int pcre_info(const pcre *<i>code</i>, int *<i>optptr</i>, int</b>
1061<b>*<i>firstcharptr</i>);</b>
1062</P>
1063<P>
1064The <b>pcre_info()</b> function is now obsolete because its interface is too
1065restrictive to return all the available data about a compiled pattern. New
1066programs should use <b>pcre_fullinfo()</b> instead. The yield of
1067<b>pcre_info()</b> is the number of capturing subpatterns, or one of the
1068following negative numbers:
1069<pre>
1070  PCRE_ERROR_NULL       the argument <i>code</i> was NULL
1071  PCRE_ERROR_BADMAGIC   the "magic number" was not found
1072</pre>
1073If the <i>optptr</i> argument is not NULL, a copy of the options with which the
1074pattern was compiled is placed in the integer it points to (see
1075PCRE_INFO_OPTIONS above).
1076</P>
1077<P>
1078If the pattern is not anchored and the <i>firstcharptr</i> argument is not NULL,
1079it is used to pass back information about the first character of any matched
1080string (see PCRE_INFO_FIRSTBYTE above).
1081</P>
1082<br><a name="SEC13" href="#TOC1">REFERENCE COUNTS</a><br>
1083<P>
1084<b>int pcre_refcount(pcre *<i>code</i>, int <i>adjust</i>);</b>
1085</P>
1086<P>
1087The <b>pcre_refcount()</b> function is used to maintain a reference count in the
1088data block that contains a compiled pattern. It is provided for the benefit of
1089applications that operate in an object-oriented manner, where different parts
1090of the application may be using the same compiled pattern, but you want to free
1091the block when they are all done.
1092</P>
1093<P>
1094When a pattern is compiled, the reference count field is initialized to zero.
1095It is changed only by calling this function, whose action is to add the
1096<i>adjust</i> value (which may be positive or negative) to it. The yield of the
1097function is the new value. However, the value of the count is constrained to
1098lie between 0 and 65535, inclusive. If the new value is outside these limits,
1099it is forced to the appropriate limit value.
1100</P>
1101<P>
1102Except when it is zero, the reference count is not correctly preserved if a
1103pattern is compiled on one host and then transferred to a host whose byte-order
1104is different. (This seems a highly unlikely scenario.)
1105</P>
1106<br><a name="SEC14" href="#TOC1">MATCHING A PATTERN: THE TRADITIONAL FUNCTION</a><br>
1107<P>
1108<b>int pcre_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b>
1109<b>const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i…

Large files files are truncated, but you can click here to view the full file