|
version 1.1, 2012/02/21 23:05:52
|
version 1.1.1.3, 2012/10/09 09:19:18
|
|
Line 14 man page, in case the conversion went wrong.
|
Line 14 man page, in case the conversion went wrong.
|
| <br> |
<br> |
| <ul> |
<ul> |
| <li><a name="TOC1" href="#SEC1">PCRE NATIVE API BASIC FUNCTIONS</a> |
<li><a name="TOC1" href="#SEC1">PCRE NATIVE API BASIC FUNCTIONS</a> |
| <li><a name="TOC2" href="#SEC2">PCRE NATIVE API AUXILIARY FUNCTIONS</a> | <li><a name="TOC2" href="#SEC2">PCRE NATIVE API STRING EXTRACTION FUNCTIONS</a> |
| <li><a name="TOC3" href="#SEC3">PCRE NATIVE API INDIRECTED FUNCTIONS</a> | <li><a name="TOC3" href="#SEC3">PCRE NATIVE API AUXILIARY FUNCTIONS</a> |
| <li><a name="TOC4" href="#SEC4">PCRE API OVERVIEW</a> | <li><a name="TOC4" href="#SEC4">PCRE NATIVE API INDIRECTED FUNCTIONS</a> |
| <li><a name="TOC5" href="#SEC5">NEWLINES</a> | <li><a name="TOC5" href="#SEC5">PCRE 8-BIT AND 16-BIT LIBRARIES</a> |
| <li><a name="TOC6" href="#SEC6">MULTITHREADING</a> | <li><a name="TOC6" href="#SEC6">PCRE API OVERVIEW</a> |
| <li><a name="TOC7" href="#SEC7">SAVING PRECOMPILED PATTERNS FOR LATER USE</a> | <li><a name="TOC7" href="#SEC7">NEWLINES</a> |
| <li><a name="TOC8" href="#SEC8">CHECKING BUILD-TIME OPTIONS</a> | <li><a name="TOC8" href="#SEC8">MULTITHREADING</a> |
| <li><a name="TOC9" href="#SEC9">COMPILING A PATTERN</a> | <li><a name="TOC9" href="#SEC9">SAVING PRECOMPILED PATTERNS FOR LATER USE</a> |
| <li><a name="TOC10" href="#SEC10">COMPILATION ERROR CODES</a> | <li><a name="TOC10" href="#SEC10">CHECKING BUILD-TIME OPTIONS</a> |
| <li><a name="TOC11" href="#SEC11">STUDYING A PATTERN</a> | <li><a name="TOC11" href="#SEC11">COMPILING A PATTERN</a> |
| <li><a name="TOC12" href="#SEC12">LOCALE SUPPORT</a> | <li><a name="TOC12" href="#SEC12">COMPILATION ERROR CODES</a> |
| <li><a name="TOC13" href="#SEC13">INFORMATION ABOUT A PATTERN</a> | <li><a name="TOC13" href="#SEC13">STUDYING A PATTERN</a> |
| <li><a name="TOC14" href="#SEC14">OBSOLETE INFO FUNCTION</a> | <li><a name="TOC14" href="#SEC14">LOCALE SUPPORT</a> |
| <li><a name="TOC15" href="#SEC15">REFERENCE COUNTS</a> | <li><a name="TOC15" href="#SEC15">INFORMATION ABOUT A PATTERN</a> |
| <li><a name="TOC16" href="#SEC16">MATCHING A PATTERN: THE TRADITIONAL FUNCTION</a> | <li><a name="TOC16" href="#SEC16">REFERENCE COUNTS</a> |
| <li><a name="TOC17" href="#SEC17">EXTRACTING CAPTURED SUBSTRINGS BY NUMBER</a> | <li><a name="TOC17" href="#SEC17">MATCHING A PATTERN: THE TRADITIONAL FUNCTION</a> |
| <li><a name="TOC18" href="#SEC18">EXTRACTING CAPTURED SUBSTRINGS BY NAME</a> | <li><a name="TOC18" href="#SEC18">EXTRACTING CAPTURED SUBSTRINGS BY NUMBER</a> |
| <li><a name="TOC19" href="#SEC19">DUPLICATE SUBPATTERN NAMES</a> | <li><a name="TOC19" href="#SEC19">EXTRACTING CAPTURED SUBSTRINGS BY NAME</a> |
| <li><a name="TOC20" href="#SEC20">FINDING ALL POSSIBLE MATCHES</a> | <li><a name="TOC20" href="#SEC20">DUPLICATE SUBPATTERN NAMES</a> |
| <li><a name="TOC21" href="#SEC21">MATCHING A PATTERN: THE ALTERNATIVE FUNCTION</a> | <li><a name="TOC21" href="#SEC21">FINDING ALL POSSIBLE MATCHES</a> |
| <li><a name="TOC22" href="#SEC22">SEE ALSO</a> | <li><a name="TOC22" href="#SEC22">OBTAINING AN ESTIMATE OF STACK USAGE</a> |
| <li><a name="TOC23" href="#SEC23">AUTHOR</a> | <li><a name="TOC23" href="#SEC23">MATCHING A PATTERN: THE ALTERNATIVE FUNCTION</a> |
| <li><a name="TOC24" href="#SEC24">REVISION</a> | <li><a name="TOC24" href="#SEC24">SEE ALSO</a> |
| | <li><a name="TOC25" href="#SEC25">AUTHOR</a> |
| | <li><a name="TOC26" href="#SEC26">REVISION</a> |
| </ul> |
</ul> |
| <br><a name="SEC1" href="#TOC1">PCRE NATIVE API BASIC FUNCTIONS</a><br> |
|
| <P> |
<P> |
| <b>#include <pcre.h></b> |
<b>#include <pcre.h></b> |
| </P> |
</P> |
| |
<br><a name="SEC1" href="#TOC1">PCRE NATIVE API BASIC FUNCTIONS</a><br> |
| <P> |
<P> |
| <b>pcre *pcre_compile(const char *<i>pattern</i>, int <i>options</i>,</b> |
<b>pcre *pcre_compile(const char *<i>pattern</i>, int <i>options</i>,</b> |
| <b>const char **<i>errptr</i>, int *<i>erroffset</i>,</b> |
<b>const char **<i>errptr</i>, int *<i>erroffset</i>,</b> |
|
Line 65 man page, in case the conversion went wrong.
|
Line 67 man page, in case the conversion went wrong.
|
| <b>const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b> |
<b>const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b> |
| <b>int <i>options</i>, int *<i>ovector</i>, int <i>ovecsize</i>);</b> |
<b>int <i>options</i>, int *<i>ovector</i>, int <i>ovecsize</i>);</b> |
| </P> |
</P> |
| <br><a name="SEC2" href="#TOC1">PCRE NATIVE API AUXILIARY FUNCTIONS</a><br> |
|
| <P> |
<P> |
| <b>pcre_jit_stack *pcre_jit_stack_alloc(int <i>startsize</i>, int <i>maxsize</i>);</b> |
|
| </P> |
|
| <P> |
|
| <b>void pcre_jit_stack_free(pcre_jit_stack *<i>stack</i>);</b> |
|
| </P> |
|
| <P> |
|
| <b>void pcre_assign_jit_stack(pcre_extra *<i>extra</i>,</b> |
|
| <b>pcre_jit_callback <i>callback</i>, void *<i>data</i>);</b> |
|
| </P> |
|
| <P> |
|
| <b>int pcre_dfa_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> |
<b>int pcre_dfa_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> |
| <b>const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b> |
<b>const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b> |
| <b>int <i>options</i>, int *<i>ovector</i>, int <i>ovecsize</i>,</b> |
<b>int <i>options</i>, int *<i>ovector</i>, int <i>ovecsize</i>,</b> |
| <b>int *<i>workspace</i>, int <i>wscount</i>);</b> |
<b>int *<i>workspace</i>, int <i>wscount</i>);</b> |
| </P> |
</P> |
| |
<br><a name="SEC2" href="#TOC1">PCRE NATIVE API STRING EXTRACTION FUNCTIONS</a><br> |
| <P> |
<P> |
| <b>int pcre_copy_named_substring(const pcre *<i>code</i>,</b> |
<b>int pcre_copy_named_substring(const pcre *<i>code</i>,</b> |
| <b>const char *<i>subject</i>, int *<i>ovector</i>,</b> |
<b>const char *<i>subject</i>, int *<i>ovector</i>,</b> |
|
Line 122 man page, in case the conversion went wrong.
|
Line 114 man page, in case the conversion went wrong.
|
| <P> |
<P> |
| <b>void pcre_free_substring_list(const char **<i>stringptr</i>);</b> |
<b>void pcre_free_substring_list(const char **<i>stringptr</i>);</b> |
| </P> |
</P> |
| |
<br><a name="SEC3" href="#TOC1">PCRE NATIVE API AUXILIARY FUNCTIONS</a><br> |
| <P> |
<P> |
| |
<b>pcre_jit_stack *pcre_jit_stack_alloc(int <i>startsize</i>, int <i>maxsize</i>);</b> |
| |
</P> |
| |
<P> |
| |
<b>void pcre_jit_stack_free(pcre_jit_stack *<i>stack</i>);</b> |
| |
</P> |
| |
<P> |
| |
<b>void pcre_assign_jit_stack(pcre_extra *<i>extra</i>,</b> |
| |
<b>pcre_jit_callback <i>callback</i>, void *<i>data</i>);</b> |
| |
</P> |
| |
<P> |
| <b>const unsigned char *pcre_maketables(void);</b> |
<b>const unsigned char *pcre_maketables(void);</b> |
| </P> |
</P> |
| <P> |
<P> |
|
Line 130 man page, in case the conversion went wrong.
|
Line 133 man page, in case the conversion went wrong.
|
| <b>int <i>what</i>, void *<i>where</i>);</b> |
<b>int <i>what</i>, void *<i>where</i>);</b> |
| </P> |
</P> |
| <P> |
<P> |
| <b>int pcre_info(const pcre *<i>code</i>, int *<i>optptr</i>, int</b> |
|
| <b>*<i>firstcharptr</i>);</b> |
|
| </P> |
|
| <P> |
|
| <b>int pcre_refcount(pcre *<i>code</i>, int <i>adjust</i>);</b> |
<b>int pcre_refcount(pcre *<i>code</i>, int <i>adjust</i>);</b> |
| </P> |
</P> |
| <P> |
<P> |
| <b>int pcre_config(int <i>what</i>, void *<i>where</i>);</b> |
<b>int pcre_config(int <i>what</i>, void *<i>where</i>);</b> |
| </P> |
</P> |
| <P> |
<P> |
| <b>char *pcre_version(void);</b> | <b>const char *pcre_version(void);</b> |
| </P> |
</P> |
| <br><a name="SEC3" href="#TOC1">PCRE NATIVE API INDIRECTED FUNCTIONS</a><br> |
|
| <P> |
<P> |
| |
<b>int pcre_pattern_to_host_byte_order(pcre *<i>code</i>,</b> |
| |
<b>pcre_extra *<i>extra</i>, const unsigned char *<i>tables</i>);</b> |
| |
</P> |
| |
<br><a name="SEC4" href="#TOC1">PCRE NATIVE API INDIRECTED FUNCTIONS</a><br> |
| |
<P> |
| <b>void *(*pcre_malloc)(size_t);</b> |
<b>void *(*pcre_malloc)(size_t);</b> |
| </P> |
</P> |
| <P> |
<P> |
|
Line 158 man page, in case the conversion went wrong.
|
Line 161 man page, in case the conversion went wrong.
|
| <P> |
<P> |
| <b>int (*pcre_callout)(pcre_callout_block *);</b> |
<b>int (*pcre_callout)(pcre_callout_block *);</b> |
| </P> |
</P> |
| <br><a name="SEC4" href="#TOC1">PCRE API OVERVIEW</a><br> | <br><a name="SEC5" href="#TOC1">PCRE 8-BIT AND 16-BIT LIBRARIES</a><br> |
| <P> |
<P> |
| |
From release 8.30, PCRE can be compiled as a library for handling 16-bit |
| |
character strings as well as, or instead of, the original library that handles |
| |
8-bit character strings. To avoid too much complication, this document |
| |
describes the 8-bit versions of the functions, with only occasional references |
| |
to the 16-bit library. |
| |
</P> |
| |
<P> |
| |
The 16-bit functions operate in the same way as their 8-bit counterparts; they |
| |
just use different data types for their arguments and results, and their names |
| |
start with <b>pcre16_</b> instead of <b>pcre_</b>. For every option that has UTF8 |
| |
in its name (for example, PCRE_UTF8), there is a corresponding 16-bit name with |
| |
UTF8 replaced by UTF16. This facility is in fact just cosmetic; the 16-bit |
| |
option names define the same bit values. |
| |
</P> |
| |
<P> |
| |
References to bytes and UTF-8 in this document should be read as references to |
| |
16-bit data quantities and UTF-16 when using the 16-bit library, unless |
| |
specified otherwise. More details of the specific differences for the 16-bit |
| |
library are given in the |
| |
<a href="pcre16.html"><b>pcre16</b></a> |
| |
page. |
| |
</P> |
| |
<br><a name="SEC6" href="#TOC1">PCRE API OVERVIEW</a><br> |
| |
<P> |
| PCRE has its own native API, which is described in this document. There are |
PCRE has its own native API, which is described in this document. There are |
| also some wrapper functions that correspond to the POSIX regular expression | also some wrapper functions (for the 8-bit library only) that correspond to the |
| API, but they do not give access to all the functionality. They are described | POSIX regular expression API, but they do not give access to all the |
| in the | functionality. They are described in the |
| <a href="pcreposix.html"><b>pcreposix</b></a> |
<a href="pcreposix.html"><b>pcreposix</b></a> |
| documentation. Both of these APIs define a set of C function calls. A C++ |
documentation. Both of these APIs define a set of C function calls. A C++ |
| wrapper is also distributed with PCRE. It is documented in the | wrapper (again for the 8-bit library only) is also distributed with PCRE. It is |
| | documented in the |
| <a href="pcrecpp.html"><b>pcrecpp</b></a> |
<a href="pcrecpp.html"><b>pcrecpp</b></a> |
| page. |
page. |
| </P> |
</P> |
| <P> |
<P> |
| The native API C function prototypes are defined in the header file |
The native API C function prototypes are defined in the header file |
| <b>pcre.h</b>, and on Unix systems the library itself is called <b>libpcre</b>. | <b>pcre.h</b>, and on Unix-like systems the (8-bit) library itself is called |
| It can normally be accessed by adding <b>-lpcre</b> to the command for linking | <b>libpcre</b>. It can normally be accessed by adding <b>-lpcre</b> to the |
| an application that uses PCRE. The header file defines the macros PCRE_MAJOR | command for linking an application that uses PCRE. The header file defines the |
| and PCRE_MINOR to contain the major and minor release numbers for the library. | macros PCRE_MAJOR and PCRE_MINOR to contain the major and minor release numbers |
| Applications can use these to include support for different releases of PCRE. | for the library. Applications can use these to include support for different |
| | releases of PCRE. |
| </P> |
</P> |
| <P> |
<P> |
| In a Windows environment, if you want to statically link an application program |
In a Windows environment, if you want to statically link an application program |
|
Line 244 internal tables that are generated when PCRE is built
|
Line 273 internal tables that are generated when PCRE is built
|
| </P> |
</P> |
| <P> |
<P> |
| The function <b>pcre_fullinfo()</b> is used to find out information about a |
The function <b>pcre_fullinfo()</b> is used to find out information about a |
| compiled pattern; <b>pcre_info()</b> is an obsolete version that returns only | compiled pattern. The function <b>pcre_version()</b> returns a pointer to a |
| some of the available information, but is retained for backwards compatibility. | string containing the version of PCRE and its date of release. |
| The function <b>pcre_version()</b> returns a pointer to a string containing the | |
| version of PCRE and its date of release. | |
| </P> |
</P> |
| <P> |
<P> |
| The function <b>pcre_refcount()</b> maintains a reference count in a data block |
The function <b>pcre_refcount()</b> maintains a reference count in a data block |
|
Line 284 points during a matching operation. Details are given
|
Line 311 points during a matching operation. Details are given
|
| <a href="pcrecallout.html"><b>pcrecallout</b></a> |
<a href="pcrecallout.html"><b>pcrecallout</b></a> |
| documentation. |
documentation. |
| <a name="newlines"></a></P> |
<a name="newlines"></a></P> |
| <br><a name="SEC5" href="#TOC1">NEWLINES</a><br> | <br><a name="SEC7" href="#TOC1">NEWLINES</a><br> |
| <P> |
<P> |
| PCRE supports five different conventions for indicating line breaks in |
PCRE supports five different conventions for indicating line breaks in |
| strings: a single CR (carriage return) character, a single LF (linefeed) |
strings: a single CR (carriage return) character, a single LF (linefeed) |
| character, the two-character sequence CRLF, any of the three preceding, or any |
character, the two-character sequence CRLF, any of the three preceding, or any |
| Unicode newline sequence. The Unicode newline sequences are the three just |
Unicode newline sequence. The Unicode newline sequences are the three just |
| mentioned, plus the single characters VT (vertical tab, U+000B), FF (formfeed, | mentioned, plus the single characters VT (vertical tab, U+000B), FF (form feed, |
| U+000C), NEL (next line, U+0085), LS (line separator, U+2028), and PS |
U+000C), NEL (next line, U+0085), LS (line separator, U+2028), and PS |
| (paragraph separator, U+2029). |
(paragraph separator, U+2029). |
| </P> |
</P> |
|
Line 323 The choice of newline convention does not affect the i
|
Line 350 The choice of newline convention does not affect the i
|
| the \n or \r escape sequences, nor does it affect what \R matches, which is |
the \n or \r escape sequences, nor does it affect what \R matches, which is |
| controlled in a similar way, but by separate options. |
controlled in a similar way, but by separate options. |
| </P> |
</P> |
| <br><a name="SEC6" href="#TOC1">MULTITHREADING</a><br> | <br><a name="SEC8" href="#TOC1">MULTITHREADING</a><br> |
| <P> |
<P> |
| The PCRE functions can be used in multi-threading applications, with the |
The PCRE functions can be used in multi-threading applications, with the |
| proviso that the memory management functions pointed to by <b>pcre_malloc</b>, |
proviso that the memory management functions pointed to by <b>pcre_malloc</b>, |
|
Line 340 memory stack areas for each thread. See the
|
Line 367 memory stack areas for each thread. See the
|
| <a href="pcrejit.html"><b>pcrejit</b></a> |
<a href="pcrejit.html"><b>pcrejit</b></a> |
| documentation for more details. |
documentation for more details. |
| </P> |
</P> |
| <br><a name="SEC7" href="#TOC1">SAVING PRECOMPILED PATTERNS FOR LATER USE</a><br> | <br><a name="SEC9" href="#TOC1">SAVING PRECOMPILED PATTERNS FOR LATER USE</a><br> |
| <P> |
<P> |
| The compiled form of a regular expression can be saved and re-used at a later |
The compiled form of a regular expression can be saved and re-used at a later |
| time, possibly by a different program, and even on a host other than the one on |
time, possibly by a different program, and even on a host other than the one on |
| which it was compiled. Details are given in the |
which it was compiled. Details are given in the |
| <a href="pcreprecompile.html"><b>pcreprecompile</b></a> |
<a href="pcreprecompile.html"><b>pcreprecompile</b></a> |
| documentation. However, compiling a regular expression with one version of PCRE | documentation, which includes a description of the |
| for use with a different version is not guaranteed to work and may cause | <b>pcre_pattern_to_host_byte_order()</b> function. However, compiling a regular |
| crashes. | expression with one version of PCRE for use with a different version is not |
| | guaranteed to work and may cause crashes. |
| </P> |
</P> |
| <br><a name="SEC8" href="#TOC1">CHECKING BUILD-TIME OPTIONS</a><br> | <br><a name="SEC10" href="#TOC1">CHECKING BUILD-TIME OPTIONS</a><br> |
| <P> |
<P> |
| <b>int pcre_config(int <i>what</i>, void *<i>where</i>);</b> |
<b>int pcre_config(int <i>what</i>, void *<i>where</i>);</b> |
| </P> |
</P> |
|
Line 363 documentation has more details about these optional fe
|
Line 391 documentation has more details about these optional fe
|
| <P> |
<P> |
| The first argument for <b>pcre_config()</b> is an integer, specifying which |
The first argument for <b>pcre_config()</b> is an integer, specifying which |
| information is required; the second argument is a pointer to a variable into |
information is required; the second argument is a pointer to a variable into |
| which the information is placed. The following information is available: | which the information is placed. The returned value is zero on success, or the |
| | negative error code PCRE_ERROR_BADOPTION if the value in the first argument is |
| | not recognized. The following information is available: |
| <pre> |
<pre> |
| PCRE_CONFIG_UTF8 |
PCRE_CONFIG_UTF8 |
| </pre> |
</pre> |
| The output is an integer that is set to one if UTF-8 support is available; |
The output is an integer that is set to one if UTF-8 support is available; |
| otherwise it is set to zero. | otherwise it is set to zero. If this option is given to the 16-bit version of |
| | this function, <b>pcre16_config()</b>, the result is PCRE_ERROR_BADOPTION. |
| <pre> |
<pre> |
| |
PCRE_CONFIG_UTF16 |
| |
</pre> |
| |
The output is an integer that is set to one if UTF-16 support is available; |
| |
otherwise it is set to zero. This value should normally be given to the 16-bit |
| |
version of this function, <b>pcre16_config()</b>. If it is given to the 8-bit |
| |
version of this function, the result is PCRE_ERROR_BADOPTION. |
| |
<pre> |
| PCRE_CONFIG_UNICODE_PROPERTIES |
PCRE_CONFIG_UNICODE_PROPERTIES |
| </pre> |
</pre> |
| The output is an integer that is set to one if support for Unicode character |
The output is an integer that is set to one if support for Unicode character |
|
Line 380 properties is available; otherwise it is set to zero.
|
Line 418 properties is available; otherwise it is set to zero.
|
| The output is an integer that is set to one if support for just-in-time |
The output is an integer that is set to one if support for just-in-time |
| compiling is available; otherwise it is set to zero. |
compiling is available; otherwise it is set to zero. |
| <pre> |
<pre> |
| |
PCRE_CONFIG_JITTARGET |
| |
</pre> |
| |
The output is a pointer to a zero-terminated "const char *" string. If JIT |
| |
support is available, the string contains the name of the architecture for |
| |
which the JIT compiler is configured, for example "x86 32bit (little endian + |
| |
unaligned)". If JIT support is not available, the result is NULL. |
| |
<pre> |
| PCRE_CONFIG_NEWLINE |
PCRE_CONFIG_NEWLINE |
| </pre> |
</pre> |
| The output is an integer whose value specifies the default character sequence |
The output is an integer whose value specifies the default character sequence |
|
Line 399 or CRLF. The default can be overridden when a pattern
|
Line 444 or CRLF. The default can be overridden when a pattern
|
| PCRE_CONFIG_LINK_SIZE |
PCRE_CONFIG_LINK_SIZE |
| </pre> |
</pre> |
| The output is an integer that contains the number of bytes used for internal |
The output is an integer that contains the number of bytes used for internal |
| linkage in compiled regular expressions. The value is 2, 3, or 4. Larger values | linkage in compiled regular expressions. For the 8-bit library, the value can |
| allow larger regular expressions to be compiled, at the expense of slower | be 2, 3, or 4. For the 16-bit library, the value is either 2 or 4 and is still |
| matching. The default value of 2 is sufficient for all but the most massive | a number of bytes. The default value of 2 is sufficient for all but the most |
| patterns, since it allows the compiled pattern to be up to 64K in size. | massive patterns, since it allows the compiled pattern to be up to 64K in size. |
| | Larger values allow larger regular expressions to be compiled, at the expense |
| | of slower matching. |
| <pre> |
<pre> |
| PCRE_CONFIG_POSIX_MALLOC_THRESHOLD |
PCRE_CONFIG_POSIX_MALLOC_THRESHOLD |
| </pre> |
</pre> |
|
Line 434 of recursive function calls. In this case, <b>pcre_sta
|
Line 481 of recursive function calls. In this case, <b>pcre_sta
|
| <b>pcre_stack_free</b> are called to manage memory blocks on the heap, thus |
<b>pcre_stack_free</b> are called to manage memory blocks on the heap, thus |
| avoiding the use of the stack. |
avoiding the use of the stack. |
| </P> |
</P> |
| <br><a name="SEC9" href="#TOC1">COMPILING A PATTERN</a><br> | <br><a name="SEC11" href="#TOC1">COMPILING A PATTERN</a><br> |
| <P> |
<P> |
| <b>pcre *pcre_compile(const char *<i>pattern</i>, int <i>options</i>,</b> |
<b>pcre *pcre_compile(const char *<i>pattern</i>, int <i>options</i>,</b> |
| <b>const char **<i>errptr</i>, int *<i>erroffset</i>,</b> |
<b>const char **<i>errptr</i>, int *<i>erroffset</i>,</b> |
|
Line 477 documentation). For those options that can be differen
|
Line 524 documentation). For those options that can be differen
|
| the pattern, the contents of the <i>options</i> argument specifies their |
the pattern, the contents of the <i>options</i> argument specifies their |
| settings at the start of compilation and execution. The PCRE_ANCHORED, |
settings at the start of compilation and execution. The PCRE_ANCHORED, |
| PCRE_BSR_<i>xxx</i>, PCRE_NEWLINE_<i>xxx</i>, PCRE_NO_UTF8_CHECK, and |
PCRE_BSR_<i>xxx</i>, PCRE_NEWLINE_<i>xxx</i>, PCRE_NO_UTF8_CHECK, and |
| PCRE_NO_START_OPT options can be set at the time of matching as well as at | PCRE_NO_START_OPTIMIZE options can be set at the time of matching as well as at |
| compile time. |
compile time. |
| </P> |
</P> |
| <P> |
<P> |
|
Line 489 not try to free it. Normally, the offset from the star
|
Line 536 not try to free it. Normally, the offset from the star
|
| byte that was being processed when the error was discovered is placed in the |
byte that was being processed when the error was discovered is placed in the |
| variable pointed to by <i>erroffset</i>, which must not be NULL (if it is, an |
variable pointed to by <i>erroffset</i>, which must not be NULL (if it is, an |
| immediate error is given). However, for an invalid UTF-8 string, the offset is |
immediate error is given). However, for an invalid UTF-8 string, the offset is |
| that of the first byte of the failing character. Also, some errors are not | that of the first byte of the failing character. |
| detected until checks are carried out when the whole pattern has been scanned; | |
| in these cases the offset passed back is the length of the pattern. | |
| </P> |
</P> |
| <P> |
<P> |
| Note that the offset is in bytes, not characters, even in UTF-8 mode. It may | Some errors are not detected until the whole pattern has been scanned; in these |
| sometimes point into the middle of a UTF-8 character. | cases, the offset passed back is the length of the pattern. Note that the |
| | offset is in bytes, not characters, even in UTF-8 mode. It may sometimes point |
| | into the middle of a UTF-8 character. |
| </P> |
</P> |
| <P> |
<P> |
| If <b>pcre_compile2()</b> is used instead of <b>pcre_compile()</b>, and the |
If <b>pcre_compile2()</b> is used instead of <b>pcre_compile()</b>, and the |
|
Line 594 documentation.
|
Line 641 documentation.
|
| <pre> |
<pre> |
| PCRE_EXTENDED |
PCRE_EXTENDED |
| </pre> |
</pre> |
| If this bit is set, whitespace data characters in the pattern are totally | If this bit is set, white space data characters in the pattern are totally |
| ignored except when escaped or inside a character class. Whitespace does not | ignored except when escaped or inside a character class. White space does not |
| include the VT character (code 11). In addition, characters between an |
include the VT character (code 11). In addition, characters between an |
| unescaped # outside a character class and the next newline, inclusive, are also |
unescaped # outside a character class and the next newline, inclusive, are also |
| ignored. This is equivalent to Perl's /x option, and it can be changed within a |
ignored. This is equivalent to Perl's /x option, and it can be changed within a |
|
Line 612 happen to represent a newline do not count.
|
Line 659 happen to represent a newline do not count.
|
| </P> |
</P> |
| <P> |
<P> |
| This option makes it possible to include comments inside complicated patterns. |
This option makes it possible to include comments inside complicated patterns. |
| Note, however, that this applies only to data characters. Whitespace characters | Note, however, that this applies only to data characters. White space characters |
| may never appear within special character sequences in a pattern, for example |
may never appear within special character sequences in a pattern, for example |
| within the sequence (?( that introduces a conditional subpattern. |
within the sequence (?( that introduces a conditional subpattern. |
| <pre> |
<pre> |
|
Line 698 CRLF sequence. Setting PCRE_NEWLINE_ANYCRLF specifies
|
Line 745 CRLF sequence. Setting PCRE_NEWLINE_ANYCRLF specifies
|
| preceding sequences should be recognized. Setting PCRE_NEWLINE_ANY specifies |
preceding sequences should be recognized. Setting PCRE_NEWLINE_ANY specifies |
| that any Unicode newline sequence should be recognized. The Unicode newline |
that any Unicode newline sequence should be recognized. The Unicode newline |
| sequences are the three just mentioned, plus the single characters VT (vertical |
sequences are the three just mentioned, plus the single characters VT (vertical |
| tab, U+000B), FF (formfeed, U+000C), NEL (next line, U+0085), LS (line | tab, U+000B), FF (form feed, U+000C), NEL (next line, U+0085), LS (line |
| separator, U+2028), and PS (paragraph separator, U+2029). The last two are | separator, U+2028), and PS (paragraph separator, U+2029). For the 8-bit |
| recognized only in UTF-8 mode. | library, the last two are recognized only in UTF-8 mode. |
| </P> |
</P> |
| <P> |
<P> |
| The newline setting in the options word uses three bits that are treated |
The newline setting in the options word uses three bits that are treated |
|
Line 712 other combinations may yield unused numbers and cause
|
Line 759 other combinations may yield unused numbers and cause
|
| </P> |
</P> |
| <P> |
<P> |
| The only time that a line break in a pattern is specially recognized when |
The only time that a line break in a pattern is specially recognized when |
| compiling is when PCRE_EXTENDED is set. CR and LF are whitespace characters, | compiling is when PCRE_EXTENDED is set. CR and LF are white space characters, |
| and so are ignored in this mode. Also, an unescaped # outside a character class |
and so are ignored in this mode. Also, an unescaped # outside a character class |
| indicates a comment that lasts until after the next line break sequence. In |
indicates a comment that lasts until after the next line break sequence. In |
| other circumstances, line break sequences in patterns are treated as literal |
other circumstances, line break sequences in patterns are treated as literal |
|
Line 760 with Perl. It can also be set by a (?U) option setting
|
Line 807 with Perl. It can also be set by a (?U) option setting
|
| PCRE_UTF8 |
PCRE_UTF8 |
| </pre> |
</pre> |
| This option causes PCRE to regard both the pattern and the subject as strings |
This option causes PCRE to regard both the pattern and the subject as strings |
| of UTF-8 characters instead of single-byte character strings. However, it is | of UTF-8 characters instead of single-byte strings. However, it is available |
| available only when PCRE is built to include UTF-8 support. If not, the use | only when PCRE is built to include UTF support. If not, the use of this option |
| of this option provokes an error. Details of how this option changes the | provokes an error. Details of how this option changes the behaviour of PCRE are |
| behaviour of PCRE are given in the | given in the |
| <a href="pcreunicode.html"><b>pcreunicode</b></a> |
<a href="pcreunicode.html"><b>pcreunicode</b></a> |
| page. |
page. |
| <pre> |
<pre> |
| PCRE_NO_UTF8_CHECK |
PCRE_NO_UTF8_CHECK |
| </pre> |
</pre> |
| When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string is | When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 |
| automatically checked. There is a discussion about the | string is automatically checked. There is a discussion about the |
| <a href="pcre.html#utf8strings">validity of UTF-8 strings</a> | <a href="pcreunicode.html#utf8strings">validity of UTF-8 strings</a> |
| in the main | in the |
| <a href="pcre.html"><b>pcre</b></a> | <a href="pcreunicode.html"><b>pcreunicode</b></a> |
| page. If an invalid UTF-8 sequence of bytes is found, <b>pcre_compile()</b> | page. If an invalid UTF-8 sequence is found, <b>pcre_compile()</b> returns an |
| returns an error. If you already know that your pattern is valid, and you want | error. If you already know that your pattern is valid, and you want to skip |
| to skip this check for performance reasons, you can set the PCRE_NO_UTF8_CHECK | this check for performance reasons, you can set the PCRE_NO_UTF8_CHECK option. |
| option. When it is set, the effect of passing an invalid UTF-8 string as a | When it is set, the effect of passing an invalid UTF-8 string as a pattern is |
| pattern is undefined. It may cause your program to crash. Note that this option | undefined. It may cause your program to crash. Note that this option can also |
| can also be passed to <b>pcre_exec()</b> and <b>pcre_dfa_exec()</b>, to suppress | be passed to <b>pcre_exec()</b> and <b>pcre_dfa_exec()</b>, to suppress the |
| the UTF-8 validity checking of subject strings. | validity checking of subject strings. |
| </P> |
</P> |
| <br><a name="SEC10" href="#TOC1">COMPILATION ERROR CODES</a><br> | <br><a name="SEC12" href="#TOC1">COMPILATION ERROR CODES</a><br> |
| <P> |
<P> |
| The following table lists the error codes than may be returned by |
The following table lists the error codes than may be returned by |
| <b>pcre_compile2()</b>, along with the error messages that may be returned by |
<b>pcre_compile2()</b>, along with the error messages that may be returned by |
| both compiling functions. As PCRE has developed, some error codes have fallen | both compiling functions. Note that error messages are always 8-bit ASCII |
| out of use. To avoid confusion, they have not been re-used. | strings, even in 16-bit mode. As PCRE has developed, some error codes have |
| | fallen out of use. To avoid confusion, they have not been re-used. |
| <pre> |
<pre> |
| 0 no error |
0 no error |
| 1 \ at end of pattern |
1 \ at end of pattern |
|
Line 821 out of use. To avoid confusion, they have not been re-
|
Line 869 out of use. To avoid confusion, they have not been re-
|
| 29 (?R or (?[+-]digits must be followed by ) |
29 (?R or (?[+-]digits must be followed by ) |
| 30 unknown POSIX class name |
30 unknown POSIX class name |
| 31 POSIX collating elements are not supported |
31 POSIX collating elements are not supported |
| 32 this version of PCRE is not compiled with PCRE_UTF8 support | 32 this version of PCRE is compiled without UTF support |
| 33 [this code is not in use] |
33 [this code is not in use] |
| 34 character value in \x{...} sequence is too large |
34 character value in \x{...} sequence is too large |
| 35 invalid condition (?(0) |
35 invalid condition (?(0) |
|
Line 833 out of use. To avoid confusion, they have not been re-
|
Line 881 out of use. To avoid confusion, they have not been re-
|
| 41 unrecognized character after (?P |
41 unrecognized character after (?P |
| 42 syntax error in subpattern name (missing terminator) |
42 syntax error in subpattern name (missing terminator) |
| 43 two named subpatterns have the same name |
43 two named subpatterns have the same name |
| 44 invalid UTF-8 string | 44 invalid UTF-8 string (specifically UTF-8) |
| 45 support for \P, \p, and \X has not been compiled |
45 support for \P, \p, and \X has not been compiled |
| 46 malformed \P or \p sequence |
46 malformed \P or \p sequence |
| 47 unknown property name after \P or \p |
47 unknown property name after \P or \p |
| 48 subpattern name is too long (maximum 32 characters) |
48 subpattern name is too long (maximum 32 characters) |
| 49 too many named subpatterns (maximum 10000) |
49 too many named subpatterns (maximum 10000) |
| 50 [this code is not in use] |
50 [this code is not in use] |
| 51 octal value is greater than \377 (not in UTF-8 mode) | 51 octal value is greater than \377 in 8-bit non-UTF-8 mode |
| 52 internal error: overran compiling workspace |
52 internal error: overran compiling workspace |
| 53 internal error: previously-checked referenced subpattern |
53 internal error: previously-checked referenced subpattern |
| not found |
not found |
|
Line 859 out of use. To avoid confusion, they have not been re-
|
Line 907 out of use. To avoid confusion, they have not been re-
|
| 65 different names for subpatterns of the same number are |
65 different names for subpatterns of the same number are |
| not allowed |
not allowed |
| 66 (*MARK) must have an argument |
66 (*MARK) must have an argument |
| 67 this version of PCRE is not compiled with PCRE_UCP support | 67 this version of PCRE is not compiled with Unicode property |
| | support |
| 68 \c must be followed by an ASCII character |
68 \c must be followed by an ASCII character |
| 69 \k is not followed by a braced, angle-bracketed, or quoted name |
69 \k is not followed by a braced, angle-bracketed, or quoted name |
| |
70 internal error: unknown opcode in find_fixedlength() |
| |
71 \N is not supported in a class |
| |
72 too many forward references |
| |
73 disallowed Unicode code point (>= 0xd800 && <= 0xdfff) |
| |
74 invalid UTF-16 string (specifically UTF-16) |
| |
75 name is too long in (*MARK), (*PRUNE), (*SKIP), or (*THEN) |
| |
76 character value in \u.... sequence is too large |
| </pre> |
</pre> |
| The numbers 32 and 10000 in errors 48 and 49 are defaults; different values may |
The numbers 32 and 10000 in errors 48 and 49 are defaults; different values may |
| be used if the limits were changed when PCRE was built. |
be used if the limits were changed when PCRE was built. |
| <a name="studyingapattern"></a></P> |
<a name="studyingapattern"></a></P> |
| <br><a name="SEC11" href="#TOC1">STUDYING A PATTERN</a><br> | <br><a name="SEC13" href="#TOC1">STUDYING A PATTERN</a><br> |
| <P> |
<P> |
| <b>pcre_extra *pcre_study(const pcre *<i>code</i>, int <i>options</i></b> |
<b>pcre_extra *pcre_study(const pcre *<i>code</i>, int <i>options</i></b> |
| <b>const char **<i>errptr</i>);</b> |
<b>const char **<i>errptr</i>);</b> |
|
Line 895 wants to pass any of the other fields to <b>pcre_exec(
|
Line 951 wants to pass any of the other fields to <b>pcre_exec(
|
| <b>pcre_dfa_exec()</b>, it must set up its own <b>pcre_extra</b> block. |
<b>pcre_dfa_exec()</b>, it must set up its own <b>pcre_extra</b> block. |
| </P> |
</P> |
| <P> |
<P> |
| The second argument of <b>pcre_study()</b> contains option bits. There is only | The second argument of <b>pcre_study()</b> contains option bits. There are three |
| one option: PCRE_STUDY_JIT_COMPILE. If this is set, and the just-in-time | options: |
| compiler is available, the pattern is further compiled into machine code that | <pre> |
| executes much faster than the <b>pcre_exec()</b> matching function. If | PCRE_STUDY_JIT_COMPILE |
| the just-in-time compiler is not available, this option is ignored. All other | PCRE_STUDY_JIT_PARTIAL_HARD_COMPILE |
| bits in the <i>options</i> argument must be zero. | PCRE_STUDY_JIT_PARTIAL_SOFT_COMPILE |
| | </pre> |
| | If any of these are set, and the just-in-time compiler is available, the |
| | pattern is further compiled into machine code that executes much faster than |
| | the <b>pcre_exec()</b> interpretive matching function. If the just-in-time |
| | compiler is not available, these options are ignored. All other bits in the |
| | <i>options</i> argument must be zero. |
| </P> |
</P> |
| <P> |
<P> |
| JIT compilation is a heavyweight optimization. It can take some time for |
JIT compilation is a heavyweight optimization. It can take some time for |
|
Line 925 When you are finished with a pattern, you can free the
|
Line 987 When you are finished with a pattern, you can free the
|
| study data by calling <b>pcre_free_study()</b>. This function was added to the |
study data by calling <b>pcre_free_study()</b>. This function was added to the |
| API for release 8.20. For earlier versions, the memory could be freed with |
API for release 8.20. For earlier versions, the memory could be freed with |
| <b>pcre_free()</b>, just like the pattern itself. This will still work in cases |
<b>pcre_free()</b>, just like the pattern itself. This will still work in cases |
| where PCRE_STUDY_JIT_COMPILE is not used, but it is advisable to change to the | where JIT optimization is not used, but it is advisable to change to the new |
| new function when convenient. | function when convenient. |
| </P> |
</P> |
| <P> |
<P> |
| This is a typical way in which <b>pcre_study</b>() is used (except that in a |
This is a typical way in which <b>pcre_study</b>() is used (except that in a |
|
Line 958 in a calling program via the <b>pcre_fullinfo()</b> fu
|
Line 1020 in a calling program via the <b>pcre_fullinfo()</b> fu
|
| Studying a pattern is also useful for non-anchored patterns that do not have a |
Studying a pattern is also useful for non-anchored patterns that do not have a |
| single fixed starting character. A bitmap of possible starting bytes is |
single fixed starting character. A bitmap of possible starting bytes is |
| created. This speeds up finding a position in the subject at which to start |
created. This speeds up finding a position in the subject at which to start |
| matching. | matching. (In 16-bit mode, the bitmap is used for 16-bit values less than 256.) |
| </P> |
</P> |
| <P> |
<P> |
| These two optimizations apply to both <b>pcre_exec()</b> and |
These two optimizations apply to both <b>pcre_exec()</b> and |
| <b>pcre_dfa_exec()</b>. However, they are not used by <b>pcre_exec()</b> if | <b>pcre_dfa_exec()</b>, and the information is also used by the JIT compiler. |
| <b>pcre_study()</b> is called with the PCRE_STUDY_JIT_COMPILE option, and | The optimizations can be disabled by setting the PCRE_NO_START_OPTIMIZE option |
| just-in-time compiling is successful. The optimizations can be disabled by | when calling <b>pcre_exec()</b> or <b>pcre_dfa_exec()</b>, but if this is done, |
| setting the PCRE_NO_START_OPTIMIZE option when calling <b>pcre_exec()</b> or | JIT execution is also disabled. You might want to do this if your pattern |
| <b>pcre_dfa_exec()</b>. You might want to do this if your pattern contains | contains callouts or (*MARK) and you want to make use of these facilities in |
| callouts or (*MARK) (which cannot be handled by the JIT compiler), and you want | cases where matching fails. See the discussion of PCRE_NO_START_OPTIMIZE |
| to make use of these facilities in cases where matching fails. See the | |
| discussion of PCRE_NO_START_OPTIMIZE | |
| <a href="#execoptions">below.</a> |
<a href="#execoptions">below.</a> |
| <a name="localesupport"></a></P> |
<a name="localesupport"></a></P> |
| <br><a name="SEC12" href="#TOC1">LOCALE SUPPORT</a><br> | <br><a name="SEC14" href="#TOC1">LOCALE SUPPORT</a><br> |
| <P> |
<P> |
| PCRE handles caseless matching, and determines whether characters are letters, |
PCRE handles caseless matching, and determines whether characters are letters, |
| digits, or whatever, by reference to a set of tables, indexed by character |
digits, or whatever, by reference to a set of tables, indexed by character |
| value. When running in UTF-8 mode, this applies only to characters with codes | value. When running in UTF-8 mode, this applies only to characters |
| less than 128. By default, higher-valued codes never match escapes such as \w | with codes less than 128. By default, higher-valued codes never match escapes |
| or \d, but they can be tested with \p if PCRE is built with Unicode character | such as \w or \d, but they can be tested with \p if PCRE is built with |
| property support. Alternatively, the PCRE_UCP option can be set at compile | Unicode character property support. Alternatively, the PCRE_UCP option can be |
| time; this causes \w and friends to use Unicode property support instead of | set at compile time; this causes \w and friends to use Unicode property |
| built-in tables. The use of locales with Unicode is discouraged. If you are | support instead of built-in tables. The use of locales with Unicode is |
| handling characters with codes greater than 128, you should either use UTF-8 | discouraged. If you are handling characters with codes greater than 128, you |
| and Unicode, or use locales, but not try to mix the two. | should either use UTF-8 and Unicode, or use locales, but not try to mix the |
| | two. |
| </P> |
</P> |
| <P> |
<P> |
| PCRE contains an internal set of tables that are used when the final argument |
PCRE contains an internal set of tables that are used when the final argument |
|
Line 1033 this facility could be used to match a pattern in a di
|
Line 1094 this facility could be used to match a pattern in a di
|
| one in which it was compiled. Passing table pointers at run time is discussed |
one in which it was compiled. Passing table pointers at run time is discussed |
| below in the section on matching a pattern. |
below in the section on matching a pattern. |
| <a name="infoaboutpattern"></a></P> |
<a name="infoaboutpattern"></a></P> |
| <br><a name="SEC13" href="#TOC1">INFORMATION ABOUT A PATTERN</a><br> | <br><a name="SEC15" href="#TOC1">INFORMATION ABOUT A PATTERN</a><br> |
| <P> |
<P> |
| <b>int pcre_fullinfo(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> |
<b>int pcre_fullinfo(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> |
| <b>int <i>what</i>, void *<i>where</i>);</b> |
<b>int <i>what</i>, void *<i>where</i>);</b> |
| </P> |
</P> |
| <P> |
<P> |
| The <b>pcre_fullinfo()</b> function returns information about a compiled |
The <b>pcre_fullinfo()</b> function returns information about a compiled |
| pattern. It replaces the obsolete <b>pcre_info()</b> function, which is | pattern. It replaces the <b>pcre_info()</b> function, which was removed from the |
| nevertheless retained for backwards compability (and is documented below). | library at version 8.30, after more than 10 years of obsolescence. |
| </P> |
</P> |
| <P> |
<P> |
| The first argument for <b>pcre_fullinfo()</b> is a pointer to the compiled |
The first argument for <b>pcre_fullinfo()</b> is a pointer to the compiled |
|
Line 1051 information is required, and the fourth argument is a
|
Line 1112 information is required, and the fourth argument is a
|
| to receive the data. The yield of the function is zero for success, or one of |
to receive the data. The yield of the function is zero for success, or one of |
| the following negative numbers: |
the following negative numbers: |
| <pre> |
<pre> |
| PCRE_ERROR_NULL the argument <i>code</i> was NULL | PCRE_ERROR_NULL the argument <i>code</i> was NULL |
| the argument <i>where</i> was NULL | the argument <i>where</i> was NULL |
| PCRE_ERROR_BADMAGIC the "magic number" was not found | PCRE_ERROR_BADMAGIC the "magic number" was not found |
| PCRE_ERROR_BADOPTION the value of <i>what</i> was invalid | PCRE_ERROR_BADENDIANNESS the pattern was compiled with different |
| | endianness |
| | PCRE_ERROR_BADOPTION the value of <i>what</i> was invalid |
| </pre> |
</pre> |
| The "magic number" is placed at the start of each compiled pattern as an simple |
The "magic number" is placed at the start of each compiled pattern as an simple |
| check against passing an arbitrary memory pointer. Here is a typical call of | check against passing an arbitrary memory pointer. The endianness error can |
| <b>pcre_fullinfo()</b>, to obtain the length of the compiled pattern: | occur if a compiled pattern is saved and reloaded on a different host. Here is |
| | a typical call of <b>pcre_fullinfo()</b>, to obtain the length of the compiled |
| | pattern: |
| <pre> |
<pre> |
| int rc; |
int rc; |
| size_t length; |
size_t length; |
|
Line 1092 a NULL table pointer.
|
Line 1157 a NULL table pointer.
|
| <pre> |
<pre> |
| PCRE_INFO_FIRSTBYTE |
PCRE_INFO_FIRSTBYTE |
| </pre> |
</pre> |
| Return information about the first byte of any matched string, for a | Return information about the first data unit of any matched string, for a |
| non-anchored pattern. The fourth argument should point to an <b>int</b> | non-anchored pattern. (The name of this option refers to the 8-bit library, |
| variable. (This option used to be called PCRE_INFO_FIRSTCHAR; the old name is | where data units are bytes.) The fourth argument should point to an <b>int</b> |
| still recognized for backwards compatibility.) | variable. |
| </P> |
</P> |
| <P> |
<P> |
| If there is a fixed first byte, for example, from a pattern such as | If there is a fixed first value, for example, the letter "c" from a pattern |
| (cat|cow|coyote), its value is returned. Otherwise, if either | such as (cat|cow|coyote), its value is returned. In the 8-bit library, the |
| | value is always less than 256; in the 16-bit library the value can be up to |
| | 0xffff. |
| | </P> |
| | <P> |
| | If there is no fixed first value, and if either |
| <br> |
<br> |
| <br> |
<br> |
| (a) the pattern was compiled with the PCRE_MULTILINE option, and every branch |
(a) the pattern was compiled with the PCRE_MULTILINE option, and every branch |
|
Line 1117 returned. For anchored patterns, -2 is returned.
|
Line 1187 returned. For anchored patterns, -2 is returned.
|
| PCRE_INFO_FIRSTTABLE |
PCRE_INFO_FIRSTTABLE |
| </pre> |
</pre> |
| If the pattern was studied, and this resulted in the construction of a 256-bit |
If the pattern was studied, and this resulted in the construction of a 256-bit |
| table indicating a fixed set of bytes for the first byte in any matching | table indicating a fixed set of values for the first data unit in any matching |
| string, a pointer to the table is returned. Otherwise NULL is returned. The |
string, a pointer to the table is returned. Otherwise NULL is returned. The |
| fourth argument should point to an <b>unsigned char *</b> variable. |
fourth argument should point to an <b>unsigned char *</b> variable. |
| <pre> |
<pre> |
|
Line 1135 Return 1 if the (?J) or (?-J) option setting is used i
|
Line 1205 Return 1 if the (?J) or (?-J) option setting is used i
|
| <pre> |
<pre> |
| PCRE_INFO_JIT |
PCRE_INFO_JIT |
| </pre> |
</pre> |
| Return 1 if the pattern was studied with the PCRE_STUDY_JIT_COMPILE option, and | Return 1 if the pattern was studied with one of the JIT options, and |
| just-in-time compiling was successful. The fourth argument should point to an |
just-in-time compiling was successful. The fourth argument should point to an |
| <b>int</b> variable. A return value of 0 means that JIT support is not available |
<b>int</b> variable. A return value of 0 means that JIT support is not available |
| in this version of PCRE, or that the pattern was not studied with the | in this version of PCRE, or that the pattern was not studied with a JIT option, |
| PCRE_STUDY_JIT_COMPILE option, or that the JIT compiler could not handle this | or that the JIT compiler could not handle this particular pattern. See the |
| particular pattern. See the | |
| <a href="pcrejit.html"><b>pcrejit</b></a> |
<a href="pcrejit.html"><b>pcrejit</b></a> |
| documentation for details of what can and cannot be handled. |
documentation for details of what can and cannot be handled. |
| <pre> |
<pre> |
| PCRE_INFO_JITSIZE |
PCRE_INFO_JITSIZE |
| </pre> |
</pre> |
| If the pattern was successfully studied with the PCRE_STUDY_JIT_COMPILE option, | If the pattern was successfully studied with a JIT option, return the size of |
| return the size of the JIT compiled code, otherwise return zero. The fourth | the JIT compiled code, otherwise return zero. The fourth argument should point |
| argument should point to a <b>size_t</b> variable. | to a <b>size_t</b> variable. |
| <pre> |
<pre> |
| PCRE_INFO_LASTLITERAL |
PCRE_INFO_LASTLITERAL |
| </pre> |
</pre> |
| Return the value of the rightmost literal byte that must exist in any matched | Return the value of the rightmost literal data unit that must exist in any |
| string, other than at its start, if such a byte has been recorded. The fourth | matched string, other than at its start, if such a value has been recorded. The |
| argument should point to an <b>int</b> variable. If there is no such byte, -1 is | fourth argument should point to an <b>int</b> variable. If there is no such |
| returned. For anchored patterns, a last literal byte is recorded only if it | value, -1 is returned. For anchored patterns, a last literal value is recorded |
| follows something of variable length. For example, for the pattern | only if it follows something of variable length. For example, for the pattern |
| /^a\d+z\d+/ the returned value is "z", but for /^a\dz\d/ the returned value |
/^a\d+z\d+/ the returned value is "z", but for /^a\dz\d/ the returned value |
| is -1. |
is -1. |
| <pre> |
<pre> |
| |
PCRE_INFO_MAXLOOKBEHIND |
| |
</pre> |
| |
Return the number of characters (NB not bytes) in the longest lookbehind |
| |
assertion in the pattern. Note that the simple assertions \b and \B require a |
| |
one-character lookbehind. This information is useful when doing multi-segment |
| |
matching using the partial matching facilities. |
| |
<pre> |
| PCRE_INFO_MINLENGTH |
PCRE_INFO_MINLENGTH |
| </pre> |
</pre> |
| If the pattern was studied and a minimum length for matching subject strings |
If the pattern was studied and a minimum length for matching subject strings |
| was computed, its value is returned. Otherwise the returned value is -1. The |
was computed, its value is returned. Otherwise the returned value is -1. The |
| value is a number of characters, not bytes (this may be relevant in UTF-8 | value is a number of characters, which in UTF-8 mode may be different from the |
| mode). The fourth argument should point to an <b>int</b> variable. A | number of bytes. The fourth argument should point to an <b>int</b> variable. A |
| non-negative value is a lower bound to the length of any matching string. There |
non-negative value is a lower bound to the length of any matching string. There |
| may not be any strings of that length that do actually match, but every string |
may not be any strings of that length that do actually match, but every string |
| that does match is at least that long. |
that does match is at least that long. |
|
Line 1189 The map consists of a number of fixed-size entries. PC
|
Line 1265 The map consists of a number of fixed-size entries. PC
|
| the number of entries, and PCRE_INFO_NAMEENTRYSIZE gives the size of each |
the number of entries, and PCRE_INFO_NAMEENTRYSIZE gives the size of each |
| entry; both of these return an <b>int</b> value. The entry size depends on the |
entry; both of these return an <b>int</b> value. The entry size depends on the |
| length of the longest name. PCRE_INFO_NAMETABLE returns a pointer to the first |
length of the longest name. PCRE_INFO_NAMETABLE returns a pointer to the first |
| entry of the table (a pointer to <b>char</b>). The first two bytes of each entry | entry of the table. This is a pointer to <b>char</b> in the 8-bit library, where |
| are the number of the capturing parenthesis, most significant byte first. The | the first two bytes of each entry are the number of the capturing parenthesis, |
| rest of the entry is the corresponding name, zero terminated. | most significant byte first. In the 16-bit library, the pointer points to |
| | 16-bit data units, the first of which contains the parenthesis number. The rest |
| | of the entry is the corresponding name, zero terminated. |
| </P> |
</P> |
| <P> |
<P> |
| The names are in alphabetical order. Duplicate names may appear if (?| is used |
The names are in alphabetical order. Duplicate names may appear if (?| is used |
|
Line 1207 necessarily the case because later subpatterns may hav
|
Line 1285 necessarily the case because later subpatterns may hav
|
| </P> |
</P> |
| <P> |
<P> |
| As a simple example of the name/number table, consider the following pattern |
As a simple example of the name/number table, consider the following pattern |
| (assume PCRE_EXTENDED is set, so white space - including newlines - is | after compilation by the 8-bit library (assume PCRE_EXTENDED is set, so white |
| ignored): | space - including newlines - is ignored): |
| <pre> |
<pre> |
| (?<date> (?<year>(\d\d)?\d\d) - (?<month>\d\d) - (?<day>\d\d) ) |
(?<date> (?<year>(\d\d)?\d\d) - (?<month>\d\d) - (?<day>\d\d) ) |
| </pre> |
</pre> |
|
Line 1258 For such patterns, the PCRE_ANCHORED bit is set in the
|
Line 1336 For such patterns, the PCRE_ANCHORED bit is set in the
|
| <pre> |
<pre> |
| PCRE_INFO_SIZE |
PCRE_INFO_SIZE |
| </pre> |
</pre> |
| Return the size of the compiled pattern. The fourth argument should point to a | Return the size of the compiled pattern in bytes (for both libraries). The |
| <b>size_t</b> variable. This value does not include the size of the <b>pcre</b> | fourth argument should point to a <b>size_t</b> variable. This value does not |
| structure that is returned by <b>pcre_compile()</b>. The value that is passed as | include the size of the <b>pcre</b> structure that is returned by |
| the argument to <b>pcre_malloc()</b> when <b>pcre_compile()</b> is getting memory | <b>pcre_compile()</b>. The value that is passed as the argument to |
| in which to place the compiled data is the value returned by this option plus | <b>pcre_malloc()</b> when <b>pcre_compile()</b> is getting memory in which to |
| the size of the <b>pcre</b> structure. Studying a compiled pattern, with or | place the compiled data is the value returned by this option plus the size of |
| without JIT, does not alter the value returned by this option. | the <b>pcre</b> structure. Studying a compiled pattern, with or without JIT, |
| | does not alter the value returned by this option. |
| <pre> |
<pre> |
| PCRE_INFO_STUDYSIZE |
PCRE_INFO_STUDYSIZE |
| </pre> |
</pre> |
| Return the size of the data block pointed to by the <i>study_data</i> field in a | Return the size in bytes of the data block pointed to by the <i>study_data</i> |
| <b>pcre_extra</b> block. If <b>pcre_extra</b> is NULL, or there is no study data, | field in a <b>pcre_extra</b> block. If <b>pcre_extra</b> is NULL, or there is no |
| zero is returned. The fourth argument should point to a <b>size_t</b> variable. | study data, zero is returned. The fourth argument should point to a |
| The <i>study_data</i> field is set by <b>pcre_study()</b> to record information | <b>size_t</b> variable. The <i>study_data</i> field is set by <b>pcre_study()</b> |
| that will speed up matching (see the section entitled | to record information that will speed up matching (see the section entitled |
| <a href="#studyingapattern">"Studying a pattern"</a> |
<a href="#studyingapattern">"Studying a pattern"</a> |
| above). The format of the <i>study_data</i> block is private, but its length |
above). The format of the <i>study_data</i> block is private, but its length |
| is made available via this option so that it can be saved and restored (see the |
is made available via this option so that it can be saved and restored (see the |
| <a href="pcreprecompile.html"><b>pcreprecompile</b></a> |
<a href="pcreprecompile.html"><b>pcreprecompile</b></a> |
| documentation for details). |
documentation for details). |
| </P> |
</P> |
| <br><a name="SEC14" href="#TOC1">OBSOLETE INFO FUNCTION</a><br> | <br><a name="SEC16" href="#TOC1">REFERENCE COUNTS</a><br> |
| <P> |
<P> |
| <b>int pcre_info(const pcre *<i>code</i>, int *<i>optptr</i>, int</b> |
|
| <b>*<i>firstcharptr</i>);</b> |
|
| </P> |
|
| <P> |
|
| The <b>pcre_info()</b> function is now obsolete because its interface is too |
|
| restrictive to return all the available data about a compiled pattern. New |
|
| programs should use <b>pcre_fullinfo()</b> instead. The yield of |
|
| <b>pcre_info()</b> is the number of capturing subpatterns, or one of the |
|
| following negative numbers: |
|
| <pre> |
|
| PCRE_ERROR_NULL the argument <i>code</i> was NULL |
|
| PCRE_ERROR_BADMAGIC the "magic number" was not found |
|
| </pre> |
|
| If the <i>optptr</i> argument is not NULL, a copy of the options with which the |
|
| pattern was compiled is placed in the integer it points to (see |
|
| PCRE_INFO_OPTIONS above). |
|
| </P> |
|
| <P> |
|
| If the pattern is not anchored and the <i>firstcharptr</i> argument is not NULL, |
|
| it is used to pass back information about the first character of any matched |
|
| string (see PCRE_INFO_FIRSTBYTE above). |
|
| </P> |
|
| <br><a name="SEC15" href="#TOC1">REFERENCE COUNTS</a><br> |
|
| <P> |
|
| <b>int pcre_refcount(pcre *<i>code</i>, int <i>adjust</i>);</b> |
<b>int pcre_refcount(pcre *<i>code</i>, int <i>adjust</i>);</b> |
| </P> |
</P> |
| <P> |
<P> |
|
Line 1327 Except when it is zero, the reference count is not cor
|
Line 1382 Except when it is zero, the reference count is not cor
|
| pattern is compiled on one host and then transferred to a host whose byte-order |
pattern is compiled on one host and then transferred to a host whose byte-order |
| is different. (This seems a highly unlikely scenario.) |
is different. (This seems a highly unlikely scenario.) |
| </P> |
</P> |
| <br><a name="SEC16" href="#TOC1">MATCHING A PATTERN: THE TRADITIONAL FUNCTION</a><br> | <br><a name="SEC17" href="#TOC1">MATCHING A PATTERN: THE TRADITIONAL FUNCTION</a><br> |
| <P> |
<P> |
| <b>int pcre_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> |
<b>int pcre_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> |
| <b>const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b> |
<b>const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b> |
|
Line 1392 fields (not necessarily in this order):
|
Line 1447 fields (not necessarily in this order):
|
| const unsigned char *<i>tables</i>; |
const unsigned char *<i>tables</i>; |
| unsigned char **<i>mark</i>; |
unsigned char **<i>mark</i>; |
| </pre> |
</pre> |
| The <i>flags</i> field is a bitmap that specifies which of the other fields | In the 16-bit version of this structure, the <i>mark</i> field has type |
| are set. The flag bits are: | "PCRE_UCHAR16 **". |
| | </P> |
| | <P> |
| | The <i>flags</i> field is used to specify which of the other fields are set. The |
| | flag bits are: |
| <pre> |
<pre> |
| PCRE_EXTRA_STUDY_DATA | PCRE_EXTRA_CALLOUT_DATA |
| PCRE_EXTRA_EXECUTABLE_JIT |
PCRE_EXTRA_EXECUTABLE_JIT |
| |
PCRE_EXTRA_MARK |
| PCRE_EXTRA_MATCH_LIMIT |
PCRE_EXTRA_MATCH_LIMIT |
| PCRE_EXTRA_MATCH_LIMIT_RECURSION |
PCRE_EXTRA_MATCH_LIMIT_RECURSION |
| PCRE_EXTRA_CALLOUT_DATA | PCRE_EXTRA_STUDY_DATA |
| PCRE_EXTRA_TABLES |
PCRE_EXTRA_TABLES |
| PCRE_EXTRA_MARK |
|
| </pre> |
</pre> |
| Other flag bits should be set to zero. The <i>study_data</i> field and sometimes |
Other flag bits should be set to zero. The <i>study_data</i> field and sometimes |
| the <i>executable_jit</i> field are set in the <b>pcre_extra</b> block that is |
the <i>executable_jit</i> field are set in the <b>pcre_extra</b> block that is |
| returned by <b>pcre_study()</b>, together with the appropriate flag bits. You |
returned by <b>pcre_study()</b>, together with the appropriate flag bits. You |
| should not set these yourself, but you may add to the block by setting the | should not set these yourself, but you may add to the block by setting other |
| other fields and their corresponding flag bits. | fields and their corresponding flag bits. |
| </P> |
</P> |
| <P> |
<P> |
| The <i>match_limit</i> field provides a means of preventing PCRE from using up a |
The <i>match_limit</i> field provides a means of preventing PCRE from using up a |
|
Line 1425 in the subject string.
|
Line 1484 in the subject string.
|
| </P> |
</P> |
| <P> |
<P> |
| When <b>pcre_exec()</b> is called with a pattern that was successfully studied |
When <b>pcre_exec()</b> is called with a pattern that was successfully studied |
| with the PCRE_STUDY_JIT_COMPILE option, the way that the matching is executed | with a JIT option, the way that the matching is executed is entirely different. |
| is entirely different. However, there is still the possibility of runaway | However, there is still the possibility of runaway matching that goes on for a |
| matching that goes on for a very long time, and so the <i>match_limit</i> value | very long time, and so the <i>match_limit</i> value is also used in this case |
| is also used in this case (but in a different way) to limit how long the | (but in a different way) to limit how long the matching can continue. |
| matching can continue. | |
| </P> |
</P> |
| <P> |
<P> |
| The default value for the limit can be set when PCRE is built; the default |
The default value for the limit can be set when PCRE is built; the default |
|
Line 1450 This limit is of use only if it is set smaller than <i
|
Line 1508 This limit is of use only if it is set smaller than <i
|
| Limiting the recursion depth limits the amount of machine stack that can be |
Limiting the recursion depth limits the amount of machine stack that can be |
| used, or, when PCRE has been compiled to use memory on the heap instead of the |
used, or, when PCRE has been compiled to use memory on the heap instead of the |
| stack, the amount of heap memory that can be used. This limit is not relevant, |
stack, the amount of heap memory that can be used. This limit is not relevant, |
| and is ignored, if the pattern was successfully studied with | and is ignored, when matching is done using JIT compiled code. |
| PCRE_STUDY_JIT_COMPILE. | |
| </P> |
</P> |
| <P> |
<P> |
| The default value for <i>match_limit_recursion</i> can be set when PCRE is |
The default value for <i>match_limit_recursion</i> can be set when PCRE is |
|
Line 1482 documentation for a discussion of saving compiled patt
|
Line 1539 documentation for a discussion of saving compiled patt
|
| </P> |
</P> |
| <P> |
<P> |
| If PCRE_EXTRA_MARK is set in the <i>flags</i> field, the <i>mark</i> field must |
If PCRE_EXTRA_MARK is set in the <i>flags</i> field, the <i>mark</i> field must |
| be set to point to a <b>char *</b> variable. If the pattern contains any | be set to point to a suitable variable. If the pattern contains any |
| backtracking control verbs such as (*MARK:NAME), and the execution ends up with |
backtracking control verbs such as (*MARK:NAME), and the execution ends up with |
| a name to pass back, a pointer to the name string (zero terminated) is placed |
a name to pass back, a pointer to the name string (zero terminated) is placed |
| in the variable pointed to by the <i>mark</i> field. The names are within the |
in the variable pointed to by the <i>mark</i> field. The names are within the |
| compiled pattern; if you wish to retain such a name you must copy it before |
compiled pattern; if you wish to retain such a name you must copy it before |
| freeing the memory of a compiled pattern. If there is no name to pass back, the |
freeing the memory of a compiled pattern. If there is no name to pass back, the |
| variable pointed to by the <i>mark</i> field set to NULL. For details of the | variable pointed to by the <i>mark</i> field is set to NULL. For details of the |
| backtracking control verbs, see the section entitled |
backtracking control verbs, see the section entitled |
| <a href="pcrepattern#backtrackcontrol">"Backtracking control"</a> |
<a href="pcrepattern#backtrackcontrol">"Backtracking control"</a> |
| in the |
in the |
|
Line 1502 Option bits for <b>pcre_exec()</b>
|
Line 1559 Option bits for <b>pcre_exec()</b>
|
| The unused bits of the <i>options</i> argument for <b>pcre_exec()</b> must be |
The unused bits of the <i>options</i> argument for <b>pcre_exec()</b> must be |
| zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_<i>xxx</i>, |
zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_<i>xxx</i>, |
| PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART, |
PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART, |
| PCRE_NO_START_OPTIMIZE, PCRE_NO_UTF8_CHECK, PCRE_PARTIAL_SOFT, and | PCRE_NO_START_OPTIMIZE, PCRE_NO_UTF8_CHECK, PCRE_PARTIAL_HARD, and |
| PCRE_PARTIAL_HARD. | PCRE_PARTIAL_SOFT. |
| </P> |
</P> |
| <P> |
<P> |
| If the pattern was successfully studied with the PCRE_STUDY_JIT_COMPILE option, | If the pattern was successfully studied with one of the just-in-time (JIT) |
| the only supported options for JIT execution are PCRE_NO_UTF8_CHECK, | compile options, the only supported options for JIT execution are |
| PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, and PCRE_NOTEMPTY_ATSTART. Note in | PCRE_NO_UTF8_CHECK, PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, |
| particular that partial matching is not supported. If an unsupported option is | PCRE_NOTEMPTY_ATSTART, PCRE_PARTIAL_HARD, and PCRE_PARTIAL_SOFT. If an |
| used, JIT execution is disabled and the normal interpretive code in | unsupported option is used, JIT execution is disabled and the normal |
| <b>pcre_exec()</b> is run. | interpretive code in <b>pcre_exec()</b> is run. |
| <pre> |
<pre> |
| PCRE_ANCHORED |
PCRE_ANCHORED |
| </pre> |
</pre> |
|
Line 1634 causing performance to suffer, but ensuring that in ca
|
Line 1691 causing performance to suffer, but ensuring that in ca
|
| "no match", the callouts do occur, and that items such as (*COMMIT) and (*MARK) |
"no match", the callouts do occur, and that items such as (*COMMIT) and (*MARK) |
| are considered at every possible starting position in the subject string. If |
are considered at every possible starting position in the subject string. If |
| PCRE_NO_START_OPTIMIZE is set at compile time, it cannot be unset at matching |
PCRE_NO_START_OPTIMIZE is set at compile time, it cannot be unset at matching |
| time. | time. The use of PCRE_NO_START_OPTIMIZE disables JIT execution; when it is set, |
| | matching is always done using interpretively. |
| </P> |
</P> |
| <P> |
<P> |
| Setting PCRE_NO_START_OPTIMIZE can change the outcome of a matching operation. |
Setting PCRE_NO_START_OPTIMIZE can change the outcome of a matching operation. |
|
Line 1668 returned.
|
Line 1726 returned.
|
| </pre> |
</pre> |
| When PCRE_UTF8 is set at compile time, the validity of the subject as a UTF-8 |
When PCRE_UTF8 is set at compile time, the validity of the subject as a UTF-8 |
| string is automatically checked when <b>pcre_exec()</b> is subsequently called. |
string is automatically checked when <b>pcre_exec()</b> is subsequently called. |
| The value of <i>startoffset</i> is also checked to ensure that it points to the | The entire string is checked before any other processing takes place. The value |
| start of a UTF-8 character. There is a discussion about the validity of UTF-8 | of <i>startoffset</i> is also checked to ensure that it points to the start of a |
| strings in the | UTF-8 character. There is a discussion about the |
| <a href="pcre.html#utf8strings">section on UTF-8 support</a> | <a href="pcreunicode.html#utf8strings">validity of UTF-8 strings</a> |
| in the main | in the |
| <a href="pcre.html"><b>pcre</b></a> | <a href="pcreunicode.html"><b>pcreunicode</b></a> |
| page. If an invalid UTF-8 sequence of bytes is found, <b>pcre_exec()</b> returns | page. If an invalid sequence of bytes is found, <b>pcre_exec()</b> returns the |
| the error PCRE_ERROR_BADUTF8 or, if PCRE_PARTIAL_HARD is set and the problem is | error PCRE_ERROR_BADUTF8 or, if PCRE_PARTIAL_HARD is set and the problem is a |
| a truncated UTF-8 character at the end of the subject, PCRE_ERROR_SHORTUTF8. In | truncated character at the end of the subject, PCRE_ERROR_SHORTUTF8. In both |
| both cases, information about the precise nature of the error may also be | cases, information about the precise nature of the error may also be returned |
| returned (see the descriptions of these errors in the section entitled \fIError | (see the descriptions of these errors in the section entitled \fIError return |
| return values from\fP <b>pcre_exec()</b> | values from\fP <b>pcre_exec()</b> |
| <a href="#errorlist">below).</a> |
<a href="#errorlist">below).</a> |
| If <i>startoffset</i> contains a value that does not point to the start of a |
If <i>startoffset</i> contains a value that does not point to the start of a |
| UTF-8 character (or to the end of the subject), PCRE_ERROR_BADUTF8_OFFSET is |
UTF-8 character (or to the end of the subject), PCRE_ERROR_BADUTF8_OFFSET is |
|
Line 1691 checks for performance reasons, you can set the PCRE_N
|
Line 1749 checks for performance reasons, you can set the PCRE_N
|
| calling <b>pcre_exec()</b>. You might want to do this for the second and |
calling <b>pcre_exec()</b>. You might want to do this for the second and |
| subsequent calls to <b>pcre_exec()</b> if you are making repeated calls to find |
subsequent calls to <b>pcre_exec()</b> if you are making repeated calls to find |
| all the matches in a single subject string. However, you should be sure that |
all the matches in a single subject string. However, you should be sure that |
| the value of <i>startoffset</i> points to the start of a UTF-8 character (or the | the value of <i>startoffset</i> points to the start of a character (or the end |
| end of the subject). When PCRE_NO_UTF8_CHECK is set, the effect of passing an | of the subject). When PCRE_NO_UTF8_CHECK is set, the effect of passing an |
| invalid UTF-8 string as a subject or an invalid value of <i>startoffset</i> is | invalid string as a subject or an invalid value of <i>startoffset</i> is |
| undefined. Your program may crash. |
undefined. Your program may crash. |
| <pre> |
<pre> |
| PCRE_PARTIAL_HARD |
PCRE_PARTIAL_HARD |
|
Line 1728 The string to be matched by <b>pcre_exec()</b>
|
Line 1786 The string to be matched by <b>pcre_exec()</b>
|
| </b><br> |
</b><br> |
| <P> |
<P> |
| The subject string is passed to <b>pcre_exec()</b> as a pointer in |
The subject string is passed to <b>pcre_exec()</b> as a pointer in |
| <i>subject</i>, a length (in bytes) in <i>length</i>, and a starting byte offset | <i>subject</i>, a length in bytes in <i>length</i>, and a starting byte offset |
| in <i>startoffset</i>. If this is negative or greater than the length of the |
in <i>startoffset</i>. If this is negative or greater than the length of the |
| subject, <b>pcre_exec()</b> returns PCRE_ERROR_BADOFFSET. When the starting |
subject, <b>pcre_exec()</b> returns PCRE_ERROR_BADOFFSET. When the starting |
| offset is zero, the search for a match starts at the beginning of the subject, |
offset is zero, the search for a match starts at the beginning of the subject, |
|
Line 1823 string that it matched that is returned.
|
Line 1881 string that it matched that is returned.
|
| <P> |
<P> |
| If the vector is too small to hold all the captured substring offsets, it is |
If the vector is too small to hold all the captured substring offsets, it is |
| used as far as possible (up to two-thirds of its length), and the function |
used as far as possible (up to two-thirds of its length), and the function |
| returns a value of zero. If neither the actual string matched not any captured | returns a value of zero. If neither the actual string matched nor any captured |
| substrings are of interest, <b>pcre_exec()</b> may be called with <i>ovector</i> |
substrings are of interest, <b>pcre_exec()</b> may be called with <i>ovector</i> |
| passed as NULL and <i>ovecsize</i> as zero. However, if the pattern contains |
passed as NULL and <i>ovecsize</i> as zero. However, if the pattern contains |
| back references and the <i>ovector</i> is not big enough to remember the related |
back references and the <i>ovector</i> is not big enough to remember the related |
|
Line 2022 time.
|
Line 2080 time.
|
| <pre> |
<pre> |
| PCRE_ERROR_JIT_STACKLIMIT (-27) |
PCRE_ERROR_JIT_STACKLIMIT (-27) |
| </pre> |
</pre> |
| This error is returned when a pattern that was successfully studied using the | This error is returned when a pattern that was successfully studied using a |
| PCRE_STUDY_JIT_COMPILE option is being matched, but the memory available for | JIT compile option is being matched, but the memory available for the |
| the just-in-time processing stack is not large enough. See the | just-in-time processing stack is not large enough. See the |
| <a href="pcrejit.html"><b>pcrejit</b></a> |
<a href="pcrejit.html"><b>pcrejit</b></a> |
| documentation for more details. |
documentation for more details. |
| |
<pre> |
| |
PCRE_ERROR_BADMODE (-28) |
| |
</pre> |
| |
This error is given if a pattern that was compiled by the 8-bit library is |
| |
passed to a 16-bit library function, or vice versa. |
| |
<pre> |
| |
PCRE_ERROR_BADENDIANNESS (-29) |
| |
</pre> |
| |
This error is given if a pattern that was compiled and saved is reloaded on a |
| |
host with different endianness. The utility function |
| |
<b>pcre_pattern_to_host_byte_order()</b> can be used to convert such a pattern |
| |
so that it runs on the new host. |
| </P> |
</P> |
| <P> |
<P> |
| Error numbers -16 to -20 and -22 are not used by <b>pcre_exec()</b>. | Error numbers -16 to -20, -22, and -30 are not used by <b>pcre_exec()</b>. |
| <a name="badutf8reasons"></a></P> |
<a name="badutf8reasons"></a></P> |
| <br><b> |
<br><b> |
| Reason codes for invalid UTF-8 strings |
Reason codes for invalid UTF-8 strings |
| </b><br> |
</b><br> |
| <P> |
<P> |
| |
This section applies only to the 8-bit library. The corresponding information |
| |
for the 16-bit library is given in the |
| |
<a href="pcre16.html"><b>pcre16</b></a> |
| |
page. |
| |
</P> |
| |
<P> |
| When <b>pcre_exec()</b> returns either PCRE_ERROR_BADUTF8 or |
When <b>pcre_exec()</b> returns either PCRE_ERROR_BADUTF8 or |
| PCRE_ERROR_SHORTUTF8, and the size of the output vector (<i>ovecsize</i>) is at |
PCRE_ERROR_SHORTUTF8, and the size of the output vector (<i>ovecsize</i>) is at |
| least 2, the offset of the start of the invalid UTF-8 character is placed in |
least 2, the offset of the start of the invalid UTF-8 character is placed in |
|
Line 2104 character.
|
Line 2180 character.
|
| The first byte of a character has the value 0xfe or 0xff. These values can |
The first byte of a character has the value 0xfe or 0xff. These values can |
| never occur in a valid UTF-8 string. |
never occur in a valid UTF-8 string. |
| </P> |
</P> |
| <br><a name="SEC17" href="#TOC1">EXTRACTING CAPTURED SUBSTRINGS BY NUMBER</a><br> | <br><a name="SEC18" href="#TOC1">EXTRACTING CAPTURED SUBSTRINGS BY NUMBER</a><br> |
| <P> |
<P> |
| <b>int pcre_copy_substring(const char *<i>subject</i>, int *<i>ovector</i>,</b> |
<b>int pcre_copy_substring(const char *<i>subject</i>, int *<i>ovector</i>,</b> |
| <b>int <i>stringcount</i>, int <i>stringnumber</i>, char *<i>buffer</i>,</b> |
<b>int <i>stringcount</i>, int <i>stringnumber</i>, char *<i>buffer</i>,</b> |
|
Line 2199 linked via a special interface to another programming
|
Line 2275 linked via a special interface to another programming
|
| <b>pcre_free</b> directly; it is for these cases that the functions are |
<b>pcre_free</b> directly; it is for these cases that the functions are |
| provided. |
provided. |
| </P> |
</P> |
| <br><a name="SEC18" href="#TOC1">EXTRACTING CAPTURED SUBSTRINGS BY NAME</a><br> | <br><a name="SEC19" href="#TOC1">EXTRACTING CAPTURED SUBSTRINGS BY NAME</a><br> |
| <P> |
<P> |
| <b>int pcre_get_stringnumber(const pcre *<i>code</i>,</b> |
<b>int pcre_get_stringnumber(const pcre *<i>code</i>,</b> |
| <b>const char *<i>name</i>);</b> |
<b>const char *<i>name</i>);</b> |
|
Line 2263 names are not included in the compiled code. The match
|
Line 2339 names are not included in the compiled code. The match
|
| numbers. For this reason, the use of different names for subpatterns of the |
numbers. For this reason, the use of different names for subpatterns of the |
| same number causes an error at compile time. |
same number causes an error at compile time. |
| </P> |
</P> |
| <br><a name="SEC19" href="#TOC1">DUPLICATE SUBPATTERN NAMES</a><br> | <br><a name="SEC20" href="#TOC1">DUPLICATE SUBPATTERN NAMES</a><br> |
| <P> |
<P> |
| <b>int pcre_get_stringtable_entries(const pcre *<i>code</i>,</b> |
<b>int pcre_get_stringtable_entries(const pcre *<i>code</i>,</b> |
| <b>const char *<i>name</i>, char **<i>first</i>, char **<i>last</i>);</b> |
<b>const char *<i>name</i>, char **<i>first</i>, char **<i>last</i>);</b> |
|
Line 2301 described above in the section entitled <i>Information
|
Line 2377 described above in the section entitled <i>Information
|
| Given all the relevant entries for the name, you can extract each of their |
Given all the relevant entries for the name, you can extract each of their |
| numbers, and hence the captured data, if any. |
numbers, and hence the captured data, if any. |
| </P> |
</P> |
| <br><a name="SEC20" href="#TOC1">FINDING ALL POSSIBLE MATCHES</a><br> | <br><a name="SEC21" href="#TOC1">FINDING ALL POSSIBLE MATCHES</a><br> |
| <P> |
<P> |
| The traditional matching function uses a similar algorithm to Perl, which stops |
The traditional matching function uses a similar algorithm to Perl, which stops |
| when it finds the first match, starting at a given point in the subject. If you |
when it finds the first match, starting at a given point in the subject. If you |
|
Line 2319 When your callout function is called, extract and save
|
Line 2395 When your callout function is called, extract and save
|
| substring. Then return 1, which forces <b>pcre_exec()</b> to backtrack and try |
substring. Then return 1, which forces <b>pcre_exec()</b> to backtrack and try |
| other alternatives. Ultimately, when it runs out of matches, <b>pcre_exec()</b> |
other alternatives. Ultimately, when it runs out of matches, <b>pcre_exec()</b> |
| will yield PCRE_ERROR_NOMATCH. |
will yield PCRE_ERROR_NOMATCH. |
| |
</P> |
| |
<br><a name="SEC22" href="#TOC1">OBTAINING AN ESTIMATE OF STACK USAGE</a><br> |
| |
<P> |
| |
Matching certain patterns using <b>pcre_exec()</b> can use a lot of process |
| |
stack, which in certain environments can be rather limited in size. Some users |
| |
find it helpful to have an estimate of the amount of stack that is used by |
| |
<b>pcre_exec()</b>, to help them set recursion limits, as described in the |
| |
<a href="pcrestack.html"><b>pcrestack</b></a> |
| |
documentation. The estimate that is output by <b>pcretest</b> when called with |
| |
the <b>-m</b> and <b>-C</b> options is obtained by calling <b>pcre_exec</b> with |
| |
the values NULL, NULL, NULL, -999, and -999 for its first five arguments. |
| |
</P> |
| |
<P> |
| |
Normally, if its first argument is NULL, <b>pcre_exec()</b> immediately returns |
| |
the negative error code PCRE_ERROR_NULL, but with this special combination of |
| |
arguments, it returns instead a negative number whose absolute value is the |
| |
approximate stack frame size in bytes. (A negative number is used so that it is |
| |
clear that no match has happened.) The value is approximate because in some |
| |
cases, recursive calls to <b>pcre_exec()</b> occur when there are one or two |
| |
additional variables on the stack. |
| |
</P> |
| |
<P> |
| |
If PCRE has been compiled to use the heap instead of the stack for recursion, |
| |
the value returned is the size of each block that is obtained from the heap. |
| <a name="dfamatch"></a></P> |
<a name="dfamatch"></a></P> |
| <br><a name="SEC21" href="#TOC1">MATCHING A PATTERN: THE ALTERNATIVE FUNCTION</a><br> | <br><a name="SEC23" href="#TOC1">MATCHING A PATTERN: THE ALTERNATIVE FUNCTION</a><br> |
| <P> |
<P> |
| <b>int pcre_dfa_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> |
<b>int pcre_dfa_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> |
| <b>const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b> |
<b>const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b> |
|
Line 2494 When a recursive subpattern is processed, the matching
|
Line 2594 When a recursive subpattern is processed, the matching
|
| recursively, using private vectors for <i>ovector</i> and <i>workspace</i>. This |
recursively, using private vectors for <i>ovector</i> and <i>workspace</i>. This |
| error is given if the output vector is not large enough. This should be |
error is given if the output vector is not large enough. This should be |
| extremely rare, as a vector of size 1000 is used. |
extremely rare, as a vector of size 1000 is used. |
| |
<pre> |
| |
PCRE_ERROR_DFA_BADRESTART (-30) |
| |
</pre> |
| |
When <b>pcre_dfa_exec()</b> is called with the <b>PCRE_DFA_RESTART</b> option, |
| |
some plausibility checks are made on the contents of the workspace, which |
| |
should contain data about the previous partial match. If any of these checks |
| |
fail, this error is given. |
| </P> |
</P> |
| <br><a name="SEC22" href="#TOC1">SEE ALSO</a><br> | <br><a name="SEC24" href="#TOC1">SEE ALSO</a><br> |
| <P> |
<P> |
| <b>pcrebuild</b>(3), <b>pcrecallout</b>(3), <b>pcrecpp(3)</b>(3), | <b>pcre16</b>(3), <b>pcrebuild</b>(3), <b>pcrecallout</b>(3), <b>pcrecpp(3)</b>(3), |
| <b>pcrematching</b>(3), <b>pcrepartial</b>(3), <b>pcreposix</b>(3), |
<b>pcrematching</b>(3), <b>pcrepartial</b>(3), <b>pcreposix</b>(3), |
| <b>pcreprecompile</b>(3), <b>pcresample</b>(3), <b>pcrestack</b>(3). |
<b>pcreprecompile</b>(3), <b>pcresample</b>(3), <b>pcrestack</b>(3). |
| </P> |
</P> |
| <br><a name="SEC23" href="#TOC1">AUTHOR</a><br> | <br><a name="SEC25" href="#TOC1">AUTHOR</a><br> |
| <P> |
<P> |
| Philip Hazel |
Philip Hazel |
| <br> |
<br> |
|
Line 2510 University Computing Service
|
Line 2617 University Computing Service
|
| Cambridge CB2 3QH, England. |
Cambridge CB2 3QH, England. |
| <br> |
<br> |
| </P> |
</P> |
| <br><a name="SEC24" href="#TOC1">REVISION</a><br> | <br><a name="SEC26" href="#TOC1">REVISION</a><br> |
| <P> |
<P> |
| Last updated: 02 December 2011 | Last updated: 17 June 2012 |
| <br> |
<br> |
| Copyright © 1997-2011 University of Cambridge. | Copyright © 1997-2012 University of Cambridge. |
| <br> |
<br> |
| <p> |
<p> |
| Return to the <a href="index.html">PCRE index page</a>. |
Return to the <a href="index.html">PCRE index page</a>. |
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to pcreapi.html 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 / html