version 1.1, 2012/02/21 23:05:51
|
version 1.1.1.3, 2012/10/09 09:19:17
|
Line 1
|
Line 1
|
.TH PCREAPI 3 | .TH PCREAPI 3 "04 May 2012" "PCRE 8.31" |
.SH NAME |
.SH NAME |
PCRE - Perl-compatible regular expressions |
PCRE - Perl-compatible regular expressions |
|
.sp |
|
.B #include <pcre.h> |
|
. |
|
. |
.SH "PCRE NATIVE API BASIC FUNCTIONS" |
.SH "PCRE NATIVE API BASIC FUNCTIONS" |
.rs |
.rs |
.sp |
.sp |
.B #include <pcre.h> |
|
.PP |
|
.SM |
.SM |
.B pcre *pcre_compile(const char *\fIpattern\fP, int \fIoptions\fP, |
.B pcre *pcre_compile(const char *\fIpattern\fP, int \fIoptions\fP, |
.ti +5n |
.ti +5n |
Line 32 PCRE - Perl-compatible regular expressions
|
Line 34 PCRE - Perl-compatible regular expressions
|
.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP, |
.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP, |
.ti +5n |
.ti +5n |
.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP); |
.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP); |
. |
|
. |
|
.SH "PCRE NATIVE API AUXILIARY FUNCTIONS" |
|
.rs |
|
.sp |
|
.B pcre_jit_stack *pcre_jit_stack_alloc(int \fIstartsize\fP, int \fImaxsize\fP); |
|
.PP |
.PP |
.B void pcre_jit_stack_free(pcre_jit_stack *\fIstack\fP); |
|
.PP |
|
.B void pcre_assign_jit_stack(pcre_extra *\fIextra\fP, |
|
.ti +5n |
|
.B pcre_jit_callback \fIcallback\fP, void *\fIdata\fP); |
|
.PP |
|
.B int pcre_dfa_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP," |
.B int pcre_dfa_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP," |
.ti +5n |
.ti +5n |
.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP, |
.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP, |
Line 52 PCRE - Perl-compatible regular expressions
|
Line 42 PCRE - Perl-compatible regular expressions
|
.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP, |
.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP, |
.ti +5n |
.ti +5n |
.B int *\fIworkspace\fP, int \fIwscount\fP); |
.B int *\fIworkspace\fP, int \fIwscount\fP); |
.PP | . |
| . |
| .SH "PCRE NATIVE API STRING EXTRACTION FUNCTIONS" |
| .rs |
| .sp |
.B int pcre_copy_named_substring(const pcre *\fIcode\fP, |
.B int pcre_copy_named_substring(const pcre *\fIcode\fP, |
.ti +5n |
.ti +5n |
.B const char *\fIsubject\fP, int *\fIovector\fP, |
.B const char *\fIsubject\fP, int *\fIovector\fP, |
Line 96 PCRE - Perl-compatible regular expressions
|
Line 90 PCRE - Perl-compatible regular expressions
|
.B void pcre_free_substring(const char *\fIstringptr\fP); |
.B void pcre_free_substring(const char *\fIstringptr\fP); |
.PP |
.PP |
.B void pcre_free_substring_list(const char **\fIstringptr\fP); |
.B void pcre_free_substring_list(const char **\fIstringptr\fP); |
|
. |
|
. |
|
.SH "PCRE NATIVE API AUXILIARY FUNCTIONS" |
|
.rs |
|
.sp |
|
.B pcre_jit_stack *pcre_jit_stack_alloc(int \fIstartsize\fP, int \fImaxsize\fP); |
.PP |
.PP |
|
.B void pcre_jit_stack_free(pcre_jit_stack *\fIstack\fP); |
|
.PP |
|
.B void pcre_assign_jit_stack(pcre_extra *\fIextra\fP, |
|
.ti +5n |
|
.B pcre_jit_callback \fIcallback\fP, void *\fIdata\fP); |
|
.PP |
.B const unsigned char *pcre_maketables(void); |
.B const unsigned char *pcre_maketables(void); |
.PP |
.PP |
.B int pcre_fullinfo(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP," |
.B int pcre_fullinfo(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP," |
.ti +5n |
.ti +5n |
.B int \fIwhat\fP, void *\fIwhere\fP); |
.B int \fIwhat\fP, void *\fIwhere\fP); |
.PP |
.PP |
.B int pcre_info(const pcre *\fIcode\fP, int *\fIoptptr\fP, int |
|
.B *\fIfirstcharptr\fP); |
|
.PP |
|
.B int pcre_refcount(pcre *\fIcode\fP, int \fIadjust\fP); |
.B int pcre_refcount(pcre *\fIcode\fP, int \fIadjust\fP); |
.PP |
.PP |
.B int pcre_config(int \fIwhat\fP, void *\fIwhere\fP); |
.B int pcre_config(int \fIwhat\fP, void *\fIwhere\fP); |
.PP |
.PP |
.B char *pcre_version(void); | .B const char *pcre_version(void); |
| .PP |
| .B int pcre_pattern_to_host_byte_order(pcre *\fIcode\fP, |
| .ti +5n |
| .B pcre_extra *\fIextra\fP, const unsigned char *\fItables\fP); |
. |
. |
. |
. |
.SH "PCRE NATIVE API INDIRECTED FUNCTIONS" |
.SH "PCRE NATIVE API INDIRECTED FUNCTIONS" |
Line 127 PCRE - Perl-compatible regular expressions
|
Line 134 PCRE - Perl-compatible regular expressions
|
.B int (*pcre_callout)(pcre_callout_block *); |
.B int (*pcre_callout)(pcre_callout_block *); |
. |
. |
. |
. |
|
.SH "PCRE 8-BIT AND 16-BIT LIBRARIES" |
|
.rs |
|
.sp |
|
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 |
|
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 \fBpcre16_\fP instead of \fBpcre_\fP. 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 |
|
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 |
|
.\" HREF |
|
\fBpcre16\fP |
|
.\" |
|
page. |
|
. |
|
. |
.SH "PCRE API OVERVIEW" |
.SH "PCRE API OVERVIEW" |
.rs |
.rs |
.sp |
.sp |
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 |
.\" HREF |
.\" HREF |
\fBpcreposix\fP |
\fBpcreposix\fP |
.\" |
.\" |
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 |
.\" HREF |
.\" HREF |
\fBpcrecpp\fP |
\fBpcrecpp\fP |
.\" |
.\" |
page. |
page. |
.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 |
\fBpcre.h\fP, and on Unix systems the library itself is called \fBlibpcre\fP. | \fBpcre.h\fP, and on Unix-like systems the (8-bit) library itself is called |
It can normally be accessed by adding \fB-lpcre\fP to the command for linking | \fBlibpcre\fP. It can normally be accessed by adding \fB-lpcre\fP 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 |
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 |
against a non-dll \fBpcre.a\fP file, you must define PCRE_STATIC before |
against a non-dll \fBpcre.a\fP file, you must define PCRE_STATIC before |
Line 218 specialist use. Most commonly, no special tables are p
|
Line 253 specialist use. Most commonly, no special tables are p
|
internal tables that are generated when PCRE is built are used. |
internal tables that are generated when PCRE is built are used. |
.P |
.P |
The function \fBpcre_fullinfo()\fP is used to find out information about a |
The function \fBpcre_fullinfo()\fP is used to find out information about a |
compiled pattern; \fBpcre_info()\fP is an obsolete version that returns only | compiled pattern. The function \fBpcre_version()\fP 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 \fBpcre_version()\fP returns a pointer to a string containing the | |
version of PCRE and its date of release. | |
.P |
.P |
The function \fBpcre_refcount()\fP maintains a reference count in a data block |
The function \fBpcre_refcount()\fP maintains a reference count in a data block |
containing a compiled pattern. This is provided for the benefit of |
containing a compiled pattern. This is provided for the benefit of |
Line 269 PCRE supports five different conventions for indicatin
|
Line 302 PCRE supports five different conventions for indicatin
|
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 332 which it was compiled. Details are given in the
|
Line 365 which it was compiled. Details are given in the
|
.\" HREF |
.\" HREF |
\fBpcreprecompile\fP |
\fBpcreprecompile\fP |
.\" |
.\" |
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 | \fBpcre_pattern_to_host_byte_order()\fP 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. |
. |
. |
. |
. |
.SH "CHECKING BUILD-TIME OPTIONS" |
.SH "CHECKING BUILD-TIME OPTIONS" |
Line 351 documentation has more details about these optional fe
|
Line 385 documentation has more details about these optional fe
|
.P |
.P |
The first argument for \fBpcre_config()\fP is an integer, specifying which |
The first argument for \fBpcre_config()\fP 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: |
.sp |
.sp |
PCRE_CONFIG_UTF8 |
PCRE_CONFIG_UTF8 |
.sp |
.sp |
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, \fBpcre16_config()\fP, the result is PCRE_ERROR_BADOPTION. |
.sp |
.sp |
|
PCRE_CONFIG_UTF16 |
|
.sp |
|
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, \fBpcre16_config()\fP. If it is given to the 8-bit |
|
version of this function, the result is PCRE_ERROR_BADOPTION. |
|
.sp |
PCRE_CONFIG_UNICODE_PROPERTIES |
PCRE_CONFIG_UNICODE_PROPERTIES |
.sp |
.sp |
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 368 properties is available; otherwise it is set to zero.
|
Line 412 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. |
.sp |
.sp |
|
PCRE_CONFIG_JITTARGET |
|
.sp |
|
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. |
|
.sp |
PCRE_CONFIG_NEWLINE |
PCRE_CONFIG_NEWLINE |
.sp |
.sp |
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 387 or CRLF. The default can be overridden when a pattern
|
Line 438 or CRLF. The default can be overridden when a pattern
|
PCRE_CONFIG_LINK_SIZE |
PCRE_CONFIG_LINK_SIZE |
.sp |
.sp |
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. |
.sp |
.sp |
PCRE_CONFIG_POSIX_MALLOC_THRESHOLD |
PCRE_CONFIG_POSIX_MALLOC_THRESHOLD |
.sp |
.sp |
Line 473 documentation). For those options that can be differen
|
Line 526 documentation). For those options that can be differen
|
the pattern, the contents of the \fIoptions\fP argument specifies their |
the pattern, the contents of the \fIoptions\fP 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_\fIxxx\fP, PCRE_NEWLINE_\fIxxx\fP, PCRE_NO_UTF8_CHECK, and |
PCRE_BSR_\fIxxx\fP, PCRE_NEWLINE_\fIxxx\fP, 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 |
If \fIerrptr\fP is NULL, \fBpcre_compile()\fP returns NULL immediately. |
If \fIerrptr\fP is NULL, \fBpcre_compile()\fP returns NULL immediately. |
Line 484 not try to free it. Normally, the offset from the star
|
Line 537 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 \fIerroffset\fP, which must not be NULL (if it is, an |
variable pointed to by \fIerroffset\fP, 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 |
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 |
If \fBpcre_compile2()\fP is used instead of \fBpcre_compile()\fP, and the |
If \fBpcre_compile2()\fP is used instead of \fBpcre_compile()\fP, and the |
\fIerrorcodeptr\fP argument is not NULL, a non-zero error code number is |
\fIerrorcodeptr\fP argument is not NULL, a non-zero error code number is |
Line 589 documentation.
|
Line 642 documentation.
|
.sp |
.sp |
PCRE_EXTENDED |
PCRE_EXTENDED |
.sp |
.sp |
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 608 comment is a literal newline sequence in the pattern;
|
Line 661 comment is a literal newline sequence in the pattern;
|
happen to represent a newline do not count. |
happen to represent a newline do not count. |
.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. |
.sp |
.sp |
Line 688 CRLF sequence. Setting PCRE_NEWLINE_ANYCRLF specifies
|
Line 741 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 |
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 |
as a number, giving eight possibilities. Currently only six are used (default |
as a number, giving eight possibilities. Currently only six are used (default |
Line 700 PCRE_NEWLINE_CR with PCRE_NEWLINE_LF is equivalent to
|
Line 753 PCRE_NEWLINE_CR with PCRE_NEWLINE_LF is equivalent to
|
other combinations may yield unused numbers and cause an error. |
other combinations may yield unused numbers and cause an error. |
.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 755 with Perl. It can also be set by a (?U) option setting
|
Line 808 with Perl. It can also be set by a (?U) option setting
|
PCRE_UTF8 |
PCRE_UTF8 |
.sp |
.sp |
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 |
.\" HREF |
.\" HREF |
\fBpcreunicode\fP |
\fBpcreunicode\fP |
.\" |
.\" |
Line 766 page.
|
Line 819 page.
|
.sp |
.sp |
PCRE_NO_UTF8_CHECK |
PCRE_NO_UTF8_CHECK |
.sp |
.sp |
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 |
.\" HTML <a href="pcre.html#utf8strings"> | .\" HTML <a href="pcreunicode.html#utf8strings"> |
.\" </a> |
.\" </a> |
validity of UTF-8 strings |
validity of UTF-8 strings |
.\" |
.\" |
in the main | in the |
.\" HREF |
.\" HREF |
\fBpcre\fP | \fBpcreunicode\fP |
.\" |
.\" |
page. If an invalid UTF-8 sequence of bytes is found, \fBpcre_compile()\fP | page. If an invalid UTF-8 sequence is found, \fBpcre_compile()\fP 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 \fBpcre_exec()\fP and \fBpcre_dfa_exec()\fP, to suppress | be passed to \fBpcre_exec()\fP and \fBpcre_dfa_exec()\fP, to suppress the |
the UTF-8 validity checking of subject strings. | validity checking of subject strings. |
. |
. |
. |
. |
.SH "COMPILATION ERROR CODES" |
.SH "COMPILATION ERROR CODES" |
Line 790 the UTF-8 validity checking of subject strings.
|
Line 843 the UTF-8 validity checking of subject strings.
|
.sp |
.sp |
The following table lists the error codes than may be returned by |
The following table lists the error codes than may be returned by |
\fBpcre_compile2()\fP, along with the error messages that may be returned by |
\fBpcre_compile2()\fP, 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. |
.sp |
.sp |
0 no error |
0 no error |
1 \e at end of pattern |
1 \e at end of pattern |
Line 825 out of use. To avoid confusion, they have not been re-
|
Line 879 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 \ex{...} sequence is too large |
34 character value in \ex{...} sequence is too large |
35 invalid condition (?(0) |
35 invalid condition (?(0) |
Line 837 out of use. To avoid confusion, they have not been re-
|
Line 891 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 \eP, \ep, and \eX has not been compiled |
45 support for \eP, \ep, and \eX has not been compiled |
46 malformed \eP or \ep sequence |
46 malformed \eP or \ep sequence |
47 unknown property name after \eP or \ep |
47 unknown property name after \eP or \ep |
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 \e377 (not in UTF-8 mode) | 51 octal value is greater than \e377 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 863 out of use. To avoid confusion, they have not been re-
|
Line 917 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 \ec must be followed by an ASCII character |
68 \ec must be followed by an ASCII character |
69 \ek is not followed by a braced, angle-bracketed, or quoted name |
69 \ek is not followed by a braced, angle-bracketed, or quoted name |
|
70 internal error: unknown opcode in find_fixedlength() |
|
71 \eN 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 \eu.... sequence is too large |
.sp |
.sp |
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. |
Line 902 If studying the pattern does not produce any useful in
|
Line 964 If studying the pattern does not produce any useful in
|
wants to pass any of the other fields to \fBpcre_exec()\fP or |
wants to pass any of the other fields to \fBpcre_exec()\fP or |
\fBpcre_dfa_exec()\fP, it must set up its own \fBpcre_extra\fP block. |
\fBpcre_dfa_exec()\fP, it must set up its own \fBpcre_extra\fP block. |
.P |
.P |
The second argument of \fBpcre_study()\fP contains option bits. There is only | The second argument of \fBpcre_study()\fP 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 | .sp |
executes much faster than the \fBpcre_exec()\fP 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 \fIoptions\fP argument must be zero. | PCRE_STUDY_JIT_PARTIAL_SOFT_COMPILE |
| .sp |
| 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 \fBpcre_exec()\fP interpretive matching function. If the just-in-time |
| compiler is not available, these options are ignored. All other bits in the |
| \fIoptions\fP argument must be zero. |
.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 |
patterns to be analyzed, and for one-off matches and simple patterns the |
patterns to be analyzed, and for one-off matches and simple patterns the |
Line 931 When you are finished with a pattern, you can free the
|
Line 999 When you are finished with a pattern, you can free the
|
study data by calling \fBpcre_free_study()\fP. This function was added to the |
study data by calling \fBpcre_free_study()\fP. 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 |
\fBpcre_free()\fP, just like the pattern itself. This will still work in cases |
\fBpcre_free()\fP, 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 |
This is a typical way in which \fBpcre_study\fP() is used (except that in a |
This is a typical way in which \fBpcre_study\fP() is used (except that in a |
real application there should be tests for errors): |
real application there should be tests for errors): |
Line 962 in a calling program via the \fBpcre_fullinfo()\fP fun
|
Line 1030 in a calling program via the \fBpcre_fullinfo()\fP fun
|
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 |
These two optimizations apply to both \fBpcre_exec()\fP and |
These two optimizations apply to both \fBpcre_exec()\fP and |
\fBpcre_dfa_exec()\fP. However, they are not used by \fBpcre_exec()\fP if | \fBpcre_dfa_exec()\fP, and the information is also used by the JIT compiler. |
\fBpcre_study()\fP 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 \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP, but if this is done, |
setting the PCRE_NO_START_OPTIMIZE option when calling \fBpcre_exec()\fP or | JIT execution is also disabled. You might want to do this if your pattern |
\fBpcre_dfa_exec()\fP. 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 | |
.\" HTML <a href="#execoptions"> |
.\" HTML <a href="#execoptions"> |
.\" </a> |
.\" </a> |
below. |
below. |
Line 985 below.
|
Line 1051 below.
|
.sp |
.sp |
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 \ew | with codes less than 128. By default, higher-valued codes never match escapes |
or \ed, but they can be tested with \ep if PCRE is built with Unicode character | such as \ew or \ed, but they can be tested with \ep 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 \ew and friends to use Unicode property support instead of | set at compile time; this causes \ew 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 |
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 |
of \fBpcre_compile()\fP is NULL. These are sufficient for many applications. |
of \fBpcre_compile()\fP is NULL. These are sufficient for many applications. |
Line 1046 below in the section on matching a pattern.
|
Line 1113 below in the section on matching a pattern.
|
.B int \fIwhat\fP, void *\fIwhere\fP); |
.B int \fIwhat\fP, void *\fIwhere\fP); |
.PP |
.PP |
The \fBpcre_fullinfo()\fP function returns information about a compiled |
The \fBpcre_fullinfo()\fP function returns information about a compiled |
pattern. It replaces the obsolete \fBpcre_info()\fP function, which is | pattern. It replaces the \fBpcre_info()\fP 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 |
The first argument for \fBpcre_fullinfo()\fP is a pointer to the compiled |
The first argument for \fBpcre_fullinfo()\fP is a pointer to the compiled |
pattern. The second argument is the result of \fBpcre_study()\fP, or NULL if |
pattern. The second argument is the result of \fBpcre_study()\fP, or NULL if |
Line 1056 information is required, and the fourth argument is a
|
Line 1123 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: |
.sp |
.sp |
PCRE_ERROR_NULL the argument \fIcode\fP was NULL | PCRE_ERROR_NULL the argument \fIcode\fP was NULL |
the argument \fIwhere\fP was NULL | the argument \fIwhere\fP 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 \fIwhat\fP was invalid | PCRE_ERROR_BADENDIANNESS the pattern was compiled with different |
| endianness |
| PCRE_ERROR_BADOPTION the value of \fIwhat\fP was invalid |
.sp |
.sp |
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 |
\fBpcre_fullinfo()\fP, 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 \fBpcre_fullinfo()\fP, to obtain the length of the compiled |
| pattern: |
.sp |
.sp |
int rc; |
int rc; |
size_t length; |
size_t length; |
Line 1097 a NULL table pointer.
|
Line 1168 a NULL table pointer.
|
.sp |
.sp |
PCRE_INFO_FIRSTBYTE |
PCRE_INFO_FIRSTBYTE |
.sp |
.sp |
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 \fBint\fP | 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 \fBint\fP |
still recognized for backwards compatibility.) | variable. |
.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 |
| If there is no fixed first value, and if either |
.sp |
.sp |
(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 |
starts with "^", or |
starts with "^", or |
Line 1118 returned. For anchored patterns, -2 is returned.
|
Line 1193 returned. For anchored patterns, -2 is returned.
|
PCRE_INFO_FIRSTTABLE |
PCRE_INFO_FIRSTTABLE |
.sp |
.sp |
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 \fBunsigned char *\fP variable. |
fourth argument should point to an \fBunsigned char *\fP variable. |
.sp |
.sp |
Line 1136 Return 1 if the (?J) or (?-J) option setting is used i
|
Line 1211 Return 1 if the (?J) or (?-J) option setting is used i
|
.sp |
.sp |
PCRE_INFO_JIT |
PCRE_INFO_JIT |
.sp |
.sp |
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 |
\fBint\fP variable. A return value of 0 means that JIT support is not available |
\fBint\fP 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 | |
.\" HREF |
.\" HREF |
\fBpcrejit\fP |
\fBpcrejit\fP |
.\" |
.\" |
Line 1149 documentation for details of what can and cannot be ha
|
Line 1223 documentation for details of what can and cannot be ha
|
.sp |
.sp |
PCRE_INFO_JITSIZE |
PCRE_INFO_JITSIZE |
.sp |
.sp |
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 \fBsize_t\fP variable. | to a \fBsize_t\fP variable. |
.sp |
.sp |
PCRE_INFO_LASTLITERAL |
PCRE_INFO_LASTLITERAL |
.sp |
.sp |
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 \fBint\fP variable. If there is no such byte, -1 is | fourth argument should point to an \fBint\fP 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\ed+z\ed+/ the returned value is "z", but for /^a\edz\ed/ the returned value |
/^a\ed+z\ed+/ the returned value is "z", but for /^a\edz\ed/ the returned value |
is -1. |
is -1. |
.sp |
.sp |
|
PCRE_INFO_MAXLOOKBEHIND |
|
.sp |
|
Return the number of characters (NB not bytes) in the longest lookbehind |
|
assertion in the pattern. Note that the simple assertions \eb and \eB require a |
|
one-character lookbehind. This information is useful when doing multi-segment |
|
matching using the partial matching facilities. |
|
.sp |
PCRE_INFO_MINLENGTH |
PCRE_INFO_MINLENGTH |
.sp |
.sp |
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 \fBint\fP variable. A | number of bytes. The fourth argument should point to an \fBint\fP 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 1191 The map consists of a number of fixed-size entries. PC
|
Line 1272 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 \fBint\fP value. The entry size depends on the |
entry; both of these return an \fBint\fP 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 \fBchar\fP). The first two bytes of each entry | entry of the table. This is a pointer to \fBchar\fP 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 |
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 |
to create multiple groups with the same number, as described in the |
to create multiple groups with the same number, as described in the |
Line 1212 table in the order in which they were found in the pat
|
Line 1295 table in the order in which they were found in the pat
|
necessarily the case because later subpatterns may have lower numbers. |
necessarily the case because later subpatterns may have lower numbers. |
.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): |
.sp |
.sp |
.\" JOIN |
.\" JOIN |
(?<date> (?<year>(\ed\ed)?\ed\ed) - |
(?<date> (?<year>(\ed\ed)?\ed\ed) - |
Line 1268 For such patterns, the PCRE_ANCHORED bit is set in the
|
Line 1351 For such patterns, the PCRE_ANCHORED bit is set in the
|
.sp |
.sp |
PCRE_INFO_SIZE |
PCRE_INFO_SIZE |
.sp |
.sp |
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 |
\fBsize_t\fP variable. This value does not include the size of the \fBpcre\fP | fourth argument should point to a \fBsize_t\fP variable. This value does not |
structure that is returned by \fBpcre_compile()\fP. The value that is passed as | include the size of the \fBpcre\fP structure that is returned by |
the argument to \fBpcre_malloc()\fP when \fBpcre_compile()\fP is getting memory | \fBpcre_compile()\fP. The value that is passed as the argument to |
in which to place the compiled data is the value returned by this option plus | \fBpcre_malloc()\fP when \fBpcre_compile()\fP is getting memory in which to |
the size of the \fBpcre\fP 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 \fBpcre\fP structure. Studying a compiled pattern, with or without JIT, |
| does not alter the value returned by this option. |
.sp |
.sp |
PCRE_INFO_STUDYSIZE |
PCRE_INFO_STUDYSIZE |
.sp |
.sp |
Return the size of the data block pointed to by the \fIstudy_data\fP field in a | Return the size in bytes of the data block pointed to by the \fIstudy_data\fP |
\fBpcre_extra\fP block. If \fBpcre_extra\fP is NULL, or there is no study data, | field in a \fBpcre_extra\fP block. If \fBpcre_extra\fP is NULL, or there is no |
zero is returned. The fourth argument should point to a \fBsize_t\fP variable. | study data, zero is returned. The fourth argument should point to a |
The \fIstudy_data\fP field is set by \fBpcre_study()\fP to record information | \fBsize_t\fP variable. The \fIstudy_data\fP field is set by \fBpcre_study()\fP |
that will speed up matching (see the section entitled | to record information that will speed up matching (see the section entitled |
.\" HTML <a href="#studyingapattern"> |
.\" HTML <a href="#studyingapattern"> |
.\" </a> |
.\" </a> |
"Studying a pattern" |
"Studying a pattern" |
Line 1295 is made available via this option so that it can be sa
|
Line 1379 is made available via this option so that it can be sa
|
documentation for details). |
documentation for details). |
. |
. |
. |
. |
.SH "OBSOLETE INFO FUNCTION" |
|
.rs |
|
.sp |
|
.B int pcre_info(const pcre *\fIcode\fP, int *\fIoptptr\fP, int |
|
.B *\fIfirstcharptr\fP); |
|
.PP |
|
The \fBpcre_info()\fP function is now obsolete because its interface is too |
|
restrictive to return all the available data about a compiled pattern. New |
|
programs should use \fBpcre_fullinfo()\fP instead. The yield of |
|
\fBpcre_info()\fP is the number of capturing subpatterns, or one of the |
|
following negative numbers: |
|
.sp |
|
PCRE_ERROR_NULL the argument \fIcode\fP was NULL |
|
PCRE_ERROR_BADMAGIC the "magic number" was not found |
|
.sp |
|
If the \fIoptptr\fP 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 |
|
If the pattern is not anchored and the \fIfirstcharptr\fP argument is not NULL, |
|
it is used to pass back information about the first character of any matched |
|
string (see PCRE_INFO_FIRSTBYTE above). |
|
. |
|
. |
|
.SH "REFERENCE COUNTS" |
.SH "REFERENCE COUNTS" |
.rs |
.rs |
.sp |
.sp |
Line 1411 fields (not necessarily in this order):
|
Line 1471 fields (not necessarily in this order):
|
const unsigned char *\fItables\fP; |
const unsigned char *\fItables\fP; |
unsigned char **\fImark\fP; |
unsigned char **\fImark\fP; |
.sp |
.sp |
The \fIflags\fP field is a bitmap that specifies which of the other fields | In the 16-bit version of this structure, the \fImark\fP field has type |
are set. The flag bits are: | "PCRE_UCHAR16 **". |
| .P |
| The \fIflags\fP field is used to specify which of the other fields are set. The |
| flag bits are: |
.sp |
.sp |
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 |
|
.sp |
.sp |
Other flag bits should be set to zero. The \fIstudy_data\fP field and sometimes |
Other flag bits should be set to zero. The \fIstudy_data\fP field and sometimes |
the \fIexecutable_jit\fP field are set in the \fBpcre_extra\fP block that is |
the \fIexecutable_jit\fP field are set in the \fBpcre_extra\fP block that is |
returned by \fBpcre_study()\fP, together with the appropriate flag bits. You |
returned by \fBpcre_study()\fP, 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 |
The \fImatch_limit\fP field provides a means of preventing PCRE from using up a |
The \fImatch_limit\fP field provides a means of preventing PCRE from using up a |
vast amount of resources when running patterns that are not going to match, |
vast amount of resources when running patterns that are not going to match, |
Line 1441 patterns that are not anchored, the count restarts fro
|
Line 1504 patterns that are not anchored, the count restarts fro
|
in the subject string. |
in the subject string. |
.P |
.P |
When \fBpcre_exec()\fP is called with a pattern that was successfully studied |
When \fBpcre_exec()\fP 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 \fImatch_limit\fP value | very long time, and so the \fImatch_limit\fP 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 |
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 |
default is 10 million, which handles all but the most extreme cases. You can |
default is 10 million, which handles all but the most extreme cases. You can |
Line 1463 This limit is of use only if it is set smaller than \f
|
Line 1525 This limit is of use only if it is set smaller than \f
|
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 |
The default value for \fImatch_limit_recursion\fP can be set when PCRE is |
The default value for \fImatch_limit_recursion\fP can be set when PCRE is |
built; the default default is the same value as the default for |
built; the default default is the same value as the default for |
Line 1495 called. See the
|
Line 1556 called. See the
|
documentation for a discussion of saving compiled patterns for later use. |
documentation for a discussion of saving compiled patterns for later use. |
.P |
.P |
If PCRE_EXTRA_MARK is set in the \fIflags\fP field, the \fImark\fP field must |
If PCRE_EXTRA_MARK is set in the \fIflags\fP field, the \fImark\fP field must |
be set to point to a \fBchar *\fP 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 \fImark\fP field. The names are within the |
in the variable pointed to by the \fImark\fP 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 \fImark\fP field set to NULL. For details of the | variable pointed to by the \fImark\fP field is set to NULL. For details of the |
backtracking control verbs, see the section entitled |
backtracking control verbs, see the section entitled |
.\" HTML <a href="pcrepattern#backtrackcontrol"> |
.\" HTML <a href="pcrepattern#backtrackcontrol"> |
.\" </a> |
.\" </a> |
Line 1521 documentation.
|
Line 1582 documentation.
|
The unused bits of the \fIoptions\fP argument for \fBpcre_exec()\fP must be |
The unused bits of the \fIoptions\fP argument for \fBpcre_exec()\fP must be |
zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_\fIxxx\fP, |
zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_\fIxxx\fP, |
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 |
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 |
\fBpcre_exec()\fP is run. | interpretive code in \fBpcre_exec()\fP is run. |
.sp |
.sp |
PCRE_ANCHORED |
PCRE_ANCHORED |
.sp |
.sp |
Line 1648 causing performance to suffer, but ensuring that in ca
|
Line 1709 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 |
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. |
Consider the pattern |
Consider the pattern |
Line 1681 returned.
|
Line 1743 returned.
|
.sp |
.sp |
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 \fBpcre_exec()\fP is subsequently called. |
string is automatically checked when \fBpcre_exec()\fP is subsequently called. |
The value of \fIstartoffset\fP 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 \fIstartoffset\fP 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 |
.\" HTML <a href="pcre.html#utf8strings"> | .\" HTML <a href="pcreunicode.html#utf8strings"> |
.\" </a> |
.\" </a> |
section on UTF-8 support | validity of UTF-8 strings |
.\" |
.\" |
in the main | in the |
.\" HREF |
.\" HREF |
\fBpcre\fP | \fBpcreunicode\fP |
.\" |
.\" |
page. If an invalid UTF-8 sequence of bytes is found, \fBpcre_exec()\fP returns | page. If an invalid sequence of bytes is found, \fBpcre_exec()\fP 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 \fBpcre_exec()\fP | values from\fP \fBpcre_exec()\fP |
.\" HTML <a href="#errorlist"> |
.\" HTML <a href="#errorlist"> |
.\" </a> |
.\" </a> |
below). |
below). |
Line 1711 checks for performance reasons, you can set the PCRE_N
|
Line 1773 checks for performance reasons, you can set the PCRE_N
|
calling \fBpcre_exec()\fP. You might want to do this for the second and |
calling \fBpcre_exec()\fP. You might want to do this for the second and |
subsequent calls to \fBpcre_exec()\fP if you are making repeated calls to find |
subsequent calls to \fBpcre_exec()\fP 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 \fIstartoffset\fP points to the start of a UTF-8 character (or the | the value of \fIstartoffset\fP 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 \fIstartoffset\fP is | invalid string as a subject or an invalid value of \fIstartoffset\fP is |
undefined. Your program may crash. |
undefined. Your program may crash. |
.sp |
.sp |
PCRE_PARTIAL_HARD |
PCRE_PARTIAL_HARD |
Line 1748 documentation.
|
Line 1810 documentation.
|
.rs |
.rs |
.sp |
.sp |
The subject string is passed to \fBpcre_exec()\fP as a pointer in |
The subject string is passed to \fBpcre_exec()\fP as a pointer in |
\fIsubject\fP, a length (in bytes) in \fIlength\fP, and a starting byte offset | \fIsubject\fP, a length in bytes in \fIlength\fP, and a starting byte offset |
in \fIstartoffset\fP. If this is negative or greater than the length of the |
in \fIstartoffset\fP. If this is negative or greater than the length of the |
subject, \fBpcre_exec()\fP returns PCRE_ERROR_BADOFFSET. When the starting |
subject, \fBpcre_exec()\fP 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 1836 string that it matched that is returned.
|
Line 1898 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, \fBpcre_exec()\fP may be called with \fIovector\fP |
substrings are of interest, \fBpcre_exec()\fP may be called with \fIovector\fP |
passed as NULL and \fIovecsize\fP as zero. However, if the pattern contains |
passed as NULL and \fIovecsize\fP as zero. However, if the pattern contains |
back references and the \fIovector\fP is not big enough to remember the related |
back references and the \fIovector\fP is not big enough to remember the related |
Line 2036 time.
|
Line 2098 time.
|
.sp |
.sp |
PCRE_ERROR_JIT_STACKLIMIT (-27) |
PCRE_ERROR_JIT_STACKLIMIT (-27) |
.sp |
.sp |
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 |
.\" HREF |
.\" HREF |
\fBpcrejit\fP |
\fBpcrejit\fP |
.\" |
.\" |
documentation for more details. |
documentation for more details. |
|
.sp |
|
PCRE_ERROR_BADMODE (-28) |
|
.sp |
|
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. |
|
.sp |
|
PCRE_ERROR_BADENDIANNESS (-29) |
|
.sp |
|
This error is given if a pattern that was compiled and saved is reloaded on a |
|
host with different endianness. The utility function |
|
\fBpcre_pattern_to_host_byte_order()\fP can be used to convert such a pattern |
|
so that it runs on the new host. |
.P |
.P |
Error numbers -16 to -20 and -22 are not used by \fBpcre_exec()\fP. | Error numbers -16 to -20, -22, and -30 are not used by \fBpcre_exec()\fP. |
. |
. |
. |
. |
.\" HTML <a name="badutf8reasons"></a> |
.\" HTML <a name="badutf8reasons"></a> |
.SS "Reason codes for invalid UTF-8 strings" |
.SS "Reason codes for invalid UTF-8 strings" |
.rs |
.rs |
.sp |
.sp |
|
This section applies only to the 8-bit library. The corresponding information |
|
for the 16-bit library is given in the |
|
.\" HREF |
|
\fBpcre16\fP |
|
.\" |
|
page. |
|
.P |
When \fBpcre_exec()\fP returns either PCRE_ERROR_BADUTF8 or |
When \fBpcre_exec()\fP returns either PCRE_ERROR_BADUTF8 or |
PCRE_ERROR_SHORTUTF8, and the size of the output vector (\fIovecsize\fP) is at |
PCRE_ERROR_SHORTUTF8, and the size of the output vector (\fIovecsize\fP) 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 2348 other alternatives. Ultimately, when it runs out of ma
|
Line 2429 other alternatives. Ultimately, when it runs out of ma
|
will yield PCRE_ERROR_NOMATCH. |
will yield PCRE_ERROR_NOMATCH. |
. |
. |
. |
. |
|
.SH "OBTAINING AN ESTIMATE OF STACK USAGE" |
|
.rs |
|
.sp |
|
Matching certain patterns using \fBpcre_exec()\fP 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 |
|
\fBpcre_exec()\fP, to help them set recursion limits, as described in the |
|
.\" HREF |
|
\fBpcrestack\fP |
|
.\" |
|
documentation. The estimate that is output by \fBpcretest\fP when called with |
|
the \fB-m\fP and \fB-C\fP options is obtained by calling \fBpcre_exec\fP with |
|
the values NULL, NULL, NULL, -999, and -999 for its first five arguments. |
|
.P |
|
Normally, if its first argument is NULL, \fBpcre_exec()\fP 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 \fBpcre_exec()\fP occur when there are one or two |
|
additional variables on the stack. |
|
.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. |
|
. |
|
. |
.\" HTML <a name="dfamatch"></a> |
.\" HTML <a name="dfamatch"></a> |
.SH "MATCHING A PATTERN: THE ALTERNATIVE FUNCTION" |
.SH "MATCHING A PATTERN: THE ALTERNATIVE FUNCTION" |
.rs |
.rs |
Line 2529 When a recursive subpattern is processed, the matching
|
Line 2636 When a recursive subpattern is processed, the matching
|
recursively, using private vectors for \fIovector\fP and \fIworkspace\fP. This |
recursively, using private vectors for \fIovector\fP and \fIworkspace\fP. 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. |
|
.sp |
|
PCRE_ERROR_DFA_BADRESTART (-30) |
|
.sp |
|
When \fBpcre_dfa_exec()\fP is called with the \fBPCRE_DFA_RESTART\fP 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. |
. |
. |
. |
. |
.SH "SEE ALSO" |
.SH "SEE ALSO" |
.rs |
.rs |
.sp |
.sp |
\fBpcrebuild\fP(3), \fBpcrecallout\fP(3), \fBpcrecpp(3)\fP(3), | \fBpcre16\fP(3), \fBpcrebuild\fP(3), \fBpcrecallout\fP(3), \fBpcrecpp(3)\fP(3), |
\fBpcrematching\fP(3), \fBpcrepartial\fP(3), \fBpcreposix\fP(3), |
\fBpcrematching\fP(3), \fBpcrepartial\fP(3), \fBpcreposix\fP(3), |
\fBpcreprecompile\fP(3), \fBpcresample\fP(3), \fBpcrestack\fP(3). |
\fBpcreprecompile\fP(3), \fBpcresample\fP(3), \fBpcrestack\fP(3). |
. |
. |
Line 2553 Cambridge CB2 3QH, England.
|
Line 2667 Cambridge CB2 3QH, England.
|
.rs |
.rs |
.sp |
.sp |
.nf |
.nf |
Last updated: 02 December 2011 | Last updated: 17 June 2012 |
Copyright (c) 1997-2011 University of Cambridge. | Copyright (c) 1997-2012 University of Cambridge. |
.fi |
.fi |