You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by pg...@apache.org on 2007/11/26 17:50:09 UTC
svn commit: r598339 [17/37] - in /httpd/httpd/vendor/pcre/current: ./ doc/
doc/html/ testdata/
Modified: httpd/httpd/vendor/pcre/current/doc/pcreapi.3
URL: http://svn.apache.org/viewvc/httpd/httpd/vendor/pcre/current/doc/pcreapi.3?rev=598339&r1=598338&r2=598339&view=diff
==============================================================================
--- httpd/httpd/vendor/pcre/current/doc/pcreapi.3 (original)
+++ httpd/httpd/vendor/pcre/current/doc/pcreapi.3 Mon Nov 26 08:49:53 2007
@@ -1,4 +1,4 @@
-.TH PCRE 3
+.TH PCREAPI 3
.SH NAME
PCRE - Perl-compatible regular expressions
.SH "PCRE NATIVE API"
@@ -7,26 +7,38 @@
.B #include <pcre.h>
.PP
.SM
-.br
.B pcre *pcre_compile(const char *\fIpattern\fP, int \fIoptions\fP,
.ti +5n
.B const char **\fIerrptr\fP, int *\fIerroffset\fP,
.ti +5n
.B const unsigned char *\fItableptr\fP);
.PP
-.br
+.B pcre *pcre_compile2(const char *\fIpattern\fP, int \fIoptions\fP,
+.ti +5n
+.B int *\fIerrorcodeptr\fP,
+.ti +5n
+.B const char **\fIerrptr\fP, int *\fIerroffset\fP,
+.ti +5n
+.B const unsigned char *\fItableptr\fP);
+.PP
.B pcre_extra *pcre_study(const pcre *\fIcode\fP, int \fIoptions\fP,
.ti +5n
.B const char **\fIerrptr\fP);
.PP
-.br
.B int pcre_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP,"
.ti +5n
.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP,
.ti +5n
.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP);
.PP
-.br
+.B int pcre_dfa_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP,"
+.ti +5n
+.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP,
+.ti +5n
+.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP,
+.ti +5n
+.B int *\fIworkspace\fP, int \fIwscount\fP);
+.PP
.B int pcre_copy_named_substring(const pcre *\fIcode\fP,
.ti +5n
.B const char *\fIsubject\fP, int *\fIovector\fP,
@@ -35,14 +47,12 @@
.ti +5n
.B char *\fIbuffer\fP, int \fIbuffersize\fP);
.PP
-.br
.B int pcre_copy_substring(const char *\fIsubject\fP, int *\fIovector\fP,
.ti +5n
.B int \fIstringcount\fP, int \fIstringnumber\fP, char *\fIbuffer\fP,
.ti +5n
.B int \fIbuffersize\fP);
.PP
-.br
.B int pcre_get_named_substring(const pcre *\fIcode\fP,
.ti +5n
.B const char *\fIsubject\fP, int *\fIovector\fP,
@@ -51,93 +61,101 @@
.ti +5n
.B const char **\fIstringptr\fP);
.PP
-.br
.B int pcre_get_stringnumber(const pcre *\fIcode\fP,
.ti +5n
.B const char *\fIname\fP);
.PP
-.br
+.B int pcre_get_stringtable_entries(const pcre *\fIcode\fP,
+.ti +5n
+.B const char *\fIname\fP, char **\fIfirst\fP, char **\fIlast\fP);
+.PP
.B int pcre_get_substring(const char *\fIsubject\fP, int *\fIovector\fP,
.ti +5n
.B int \fIstringcount\fP, int \fIstringnumber\fP,
.ti +5n
.B const char **\fIstringptr\fP);
.PP
-.br
.B int pcre_get_substring_list(const char *\fIsubject\fP,
.ti +5n
.B int *\fIovector\fP, int \fIstringcount\fP, "const char ***\fIlistptr\fP);"
.PP
-.br
.B void pcre_free_substring(const char *\fIstringptr\fP);
.PP
-.br
.B void pcre_free_substring_list(const char **\fIstringptr\fP);
.PP
-.br
.B const unsigned char *pcre_maketables(void);
.PP
-.br
.B int pcre_fullinfo(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP,"
.ti +5n
.B int \fIwhat\fP, void *\fIwhere\fP);
.PP
-.br
.B int pcre_info(const pcre *\fIcode\fP, int *\fIoptptr\fP, int
.B *\fIfirstcharptr\fP);
.PP
-.br
+.B int pcre_refcount(pcre *\fIcode\fP, int \fIadjust\fP);
+.PP
.B int pcre_config(int \fIwhat\fP, void *\fIwhere\fP);
.PP
-.br
.B char *pcre_version(void);
.PP
-.br
.B void *(*pcre_malloc)(size_t);
.PP
-.br
.B void (*pcre_free)(void *);
.PP
-.br
.B void *(*pcre_stack_malloc)(size_t);
.PP
-.br
.B void (*pcre_stack_free)(void *);
.PP
-.br
.B int (*pcre_callout)(pcre_callout_block *);
.
.
.SH "PCRE API OVERVIEW"
.rs
.sp
-PCRE has its own native API, which is described in this document. There is also
-a set of wrapper functions that correspond to the POSIX regular expression API.
-These are described in the
+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
+API. These are described in the
.\" HREF
\fBpcreposix\fP
.\"
-documentation.
+documentation. Both of these APIs define a set of C function calls. A C++
+wrapper is distributed with PCRE. It is documented in the
+.\" HREF
+\fBpcrecpp\fP
+.\"
+page.
.P
-The native API function prototypes are defined in the header file \fBpcre.h\fP,
-and on Unix systems the library itself is called \fBlibpcre\fP. It can
-normally be accessed by adding \fB-lpcre\fP to the command for linking an
-application that uses PCRE. The header file defines the macros PCRE_MAJOR and
-PCRE_MINOR to contain the major and minor release numbers for the library.
+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.
+It can normally be accessed by adding \fB-lpcre\fP to the command for linking
+an application that uses PCRE. The header file defines the macros PCRE_MAJOR
+and PCRE_MINOR to contain the major and minor release numbers for the library.
Applications can use these to include support for different releases of PCRE.
.P
-The functions \fBpcre_compile()\fP, \fBpcre_study()\fP, and \fBpcre_exec()\fP
-are used for compiling and matching regular expressions. A sample program that
-demonstrates the simplest way of using them is provided in the file called
-\fIpcredemo.c\fP in the source distribution. The
+The functions \fBpcre_compile()\fP, \fBpcre_compile2()\fP, \fBpcre_study()\fP,
+and \fBpcre_exec()\fP are used for compiling and matching regular expressions
+in a Perl-compatible manner. A sample program that demonstrates the simplest
+way of using them is provided in the file called \fIpcredemo.c\fP in the source
+distribution. The
.\" HREF
\fBpcresample\fP
.\"
documentation describes how to run it.
.P
+A second matching function, \fBpcre_dfa_exec()\fP, which is not
+Perl-compatible, is also provided. This uses a different algorithm for the
+matching. The alternative algorithm finds all possible matches (at a given
+point in the subject), and scans the subject just once. However, this algorithm
+does not return captured substrings. A description of the two matching
+algorithms and their advantages and disadvantages is given in the
+.\" HREF
+\fBpcrematching\fP
+.\"
+documentation.
+.P
In addition to the main compiling and matching functions, there are convenience
-functions for extracting captured substrings from a matched subject string.
-They are:
+functions for extracting captured substrings from a subject string that is
+matched by \fBpcre_exec()\fP. They are:
.sp
\fBpcre_copy_substring()\fP
\fBpcre_copy_named_substring()\fP
@@ -145,15 +163,16 @@
\fBpcre_get_named_substring()\fP
\fBpcre_get_substring_list()\fP
\fBpcre_get_stringnumber()\fP
+ \fBpcre_get_stringtable_entries()\fP
.sp
\fBpcre_free_substring()\fP and \fBpcre_free_substring_list()\fP are also
provided, to free the memory used for extracted strings.
.P
The function \fBpcre_maketables()\fP is used to build a set of character tables
-in the current locale for passing to \fBpcre_compile()\fP or \fBpcre_exec()\fP.
-This is an optional facility that is provided for specialist use. Most
-commonly, no special tables are passed, in which case internal tables that are
-generated when PCRE is built are used.
+in the current locale for passing to \fBpcre_compile()\fP, \fBpcre_exec()\fP,
+or \fBpcre_dfa_exec()\fP. This is an optional facility that is provided for
+specialist use. Most commonly, no special tables are passed, in which case
+internal tables that are generated when PCRE is built are used.
.P
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
@@ -161,6 +180,10 @@
The function \fBpcre_version()\fP returns a pointer to a string containing the
version of PCRE and its date of release.
.P
+The function \fBpcre_refcount()\fP maintains a reference count in a data block
+containing a compiled pattern. This is provided for the benefit of
+object-oriented applications.
+.P
The global variables \fBpcre_malloc\fP and \fBpcre_free\fP initially contain
the entry points of the standard \fBmalloc()\fP and \fBfree()\fP functions,
respectively. PCRE calls the memory management functions via these variables,
@@ -170,12 +193,21 @@
The global variables \fBpcre_stack_malloc\fP and \fBpcre_stack_free\fP are also
indirections to memory management functions. These special functions are used
only when PCRE is compiled to use the heap for remembering data, instead of
-recursive function calls. This is a non-standard way of building PCRE, for use
-in environments that have limited stacks. Because of the greater use of memory
-management, it runs more slowly. Separate functions are provided so that
-special-purpose external code can be used for this case. When used, these
-functions are always called in a stack-like manner (last obtained, first
-freed), and always for memory blocks of the same size.
+recursive function calls, when running the \fBpcre_exec()\fP function. See the
+.\" HREF
+\fBpcrebuild\fP
+.\"
+documentation for details of how to do this. It is a non-standard way of
+building PCRE, for use in environments that have limited stacks. Because of the
+greater use of memory management, it runs more slowly. Separate functions are
+provided so that special-purpose external code can be used for this case. When
+used, these functions are always called in a stack-like manner (last obtained,
+first freed), and always for memory blocks of the same size. There is a
+discussion about PCRE's stack usage in the
+.\" HREF
+\fBpcrestack\fP
+.\"
+documentation.
.P
The global variable \fBpcre_callout\fP initially contains NULL. It can be set
by the caller to a "callout" function, which PCRE will then call at specified
@@ -186,6 +218,49 @@
documentation.
.
.
+.\" HTML <a name="newlines"></a>
+.SH NEWLINES
+.rs
+.sp
+PCRE supports five different conventions for indicating line breaks in
+strings: a single CR (carriage return) character, a single LF (linefeed)
+character, the two-character sequence CRLF, any of the three preceding, or any
+Unicode newline sequence. The Unicode newline 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 separator, U+2028), and PS
+(paragraph separator, U+2029).
+.P
+Each of the first three conventions is used by at least one operating system as
+its standard newline sequence. When PCRE is built, a default can be specified.
+The default default is LF, which is the Unix standard. When PCRE is run, the
+default can be overridden, either when a pattern is compiled, or when it is
+matched.
+.P
+At compile time, the newline convention can be specified by the \fIoptions\fP
+argument of \fBpcre_compile()\fP, or it can be specified by special text at the
+start of the pattern itself; this overrides any other settings. See the
+.\" HREF
+\fBpcrepattern\fP
+.\"
+page for details of the special character sequences.
+.P
+In the PCRE documentation the word "newline" is used to mean "the character or
+pair of characters that indicate a line break". The choice of newline
+convention affects the handling of the dot, circumflex, and dollar
+metacharacters, the handling of #-comments in /x mode, and, when CRLF is a
+recognized line ending sequence, the match position advancement for a
+non-anchored pattern. There is more detail about this in the
+.\" HTML <a href="#execoptions">
+.\" </a>
+section on \fBpcre_exec()\fP options
+.\"
+below.
+.P
+The choice of newline convention does not affect the interpretation of
+the \en or \er escape sequences, nor does it affect what \eR matches, which is
+controlled in a similar way, but by separate options.
+.
+.
.SH MULTITHREADING
.rs
.sp
@@ -207,7 +282,9 @@
.\" HREF
\fBpcreprecompile\fP
.\"
-documentation.
+documentation. However, compiling a regular 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"
@@ -238,9 +315,17 @@
.sp
PCRE_CONFIG_NEWLINE
.sp
-The output is an integer that is set to the value of the code that is used for
-the newline character. It is either linefeed (10) or carriage return (13), and
-should normally be the standard character for your operating system.
+The output is an integer whose value specifies the default character sequence
+that is recognized as meaning "newline". The four values that are supported
+are: 10 for LF, 13 for CR, 3338 for CRLF, -2 for ANYCRLF, and -1 for ANY. The
+default should normally be the standard sequence for your operating system.
+.sp
+ PCRE_CONFIG_BSR
+.sp
+The output is an integer whose value indicates what character sequences the \eR
+escape sequence matches by default. A value of 0 means that \eR matches any
+Unicode line ending sequence; a value of 1 means that \eR matches only CR, LF,
+or CRLF. The default can be overridden when a pattern is compiled or matched.
.sp
PCRE_CONFIG_LINK_SIZE
.sp
@@ -266,14 +351,21 @@
internal matching function calls in a \fBpcre_exec()\fP execution. Further
details are given with \fBpcre_exec()\fP below.
.sp
+ PCRE_CONFIG_MATCH_LIMIT_RECURSION
+.sp
+The output is an integer that gives the default limit for the depth of
+recursion when calling the internal matching function in a \fBpcre_exec()\fP
+execution. Further details are given with \fBpcre_exec()\fP below.
+.sp
PCRE_CONFIG_STACKRECURSE
.sp
-The output is an integer that is set to one if internal recursion is
-implemented by recursive function calls that use the stack to remember their
-state. This is the usual way that PCRE is compiled. The output is zero if PCRE
-was compiled to use blocks of data on the heap instead of recursive function
-calls. In this case, \fBpcre_stack_malloc\fP and \fBpcre_stack_free\fP are
-called to manage memory blocks on the heap, thus avoiding the use of the stack.
+The output is an integer that is set to one if internal recursion when running
+\fBpcre_exec()\fP is implemented by recursive function calls that use the stack
+to remember their state. This is the usual way that PCRE is compiled. The
+output is zero if PCRE was compiled to use blocks of data on the heap instead
+of recursive function calls. In this case, \fBpcre_stack_malloc\fP and
+\fBpcre_stack_free\fP are called to manage memory blocks on the heap, thus
+avoiding the use of the stack.
.
.
.SH "COMPILING A PATTERN"
@@ -284,21 +376,33 @@
.B const char **\fIerrptr\fP, int *\fIerroffset\fP,
.ti +5n
.B const unsigned char *\fItableptr\fP);
+.sp
+.B pcre *pcre_compile2(const char *\fIpattern\fP, int \fIoptions\fP,
+.ti +5n
+.B int *\fIerrorcodeptr\fP,
+.ti +5n
+.B const char **\fIerrptr\fP, int *\fIerroffset\fP,
+.ti +5n
+.B const unsigned char *\fItableptr\fP);
.P
-The function \fBpcre_compile()\fP is called to compile a pattern into an
-internal form. The pattern is a C string terminated by a binary zero, and
-is passed in the \fIpattern\fP argument. A pointer to a single block of memory
-that is obtained via \fBpcre_malloc\fP is returned. This contains the compiled
-code and related data. The \fBpcre\fP type is defined for the returned block;
-this is a typedef for a structure whose contents are not externally defined. It
-is up to the caller to free the memory when it is no longer required.
+Either of the functions \fBpcre_compile()\fP or \fBpcre_compile2()\fP can be
+called to compile a pattern into an internal form. The only difference between
+the two interfaces is that \fBpcre_compile2()\fP has an additional argument,
+\fIerrorcodeptr\fP, via which a numerical error code can be returned.
+.P
+The pattern is a C string terminated by a binary zero, and is passed in the
+\fIpattern\fP argument. A pointer to a single block of memory that is obtained
+via \fBpcre_malloc\fP is returned. This contains the compiled code and related
+data. The \fBpcre\fP type is defined for the returned block; this is a typedef
+for a structure whose contents are not externally defined. It is up to the
+caller to free the memory (via \fBpcre_free\fP) when it is no longer required.
.P
Although the compiled code of a PCRE regex is relocatable, that is, it does not
depend on memory location, the complete \fBpcre\fP data block is not
fully relocatable, because it may contain a copy of the \fItableptr\fP
argument, which is an address (see below).
.P
-The \fIoptions\fP argument contains independent bits that affect the
+The \fIoptions\fP argument contains various bit settings that affect the
compilation. It should be zero if no options are required. The available
options are described below. Some of them, in particular, those that are
compatible with Perl, can also be set and unset from within the pattern (see
@@ -308,16 +412,22 @@
.\"
documentation). For these options, the contents of the \fIoptions\fP argument
specifies their initial settings at the start of compilation and execution. The
-PCRE_ANCHORED option can be set at the time of matching as well as at compile
-time.
+PCRE_ANCHORED and PCRE_NEWLINE_\fIxxx\fP options can be set at the time of
+matching as well as at compile time.
.P
If \fIerrptr\fP is NULL, \fBpcre_compile()\fP returns NULL immediately.
Otherwise, if compilation of a pattern fails, \fBpcre_compile()\fP returns
NULL, and sets the variable pointed to by \fIerrptr\fP to point to a textual
-error message. The offset from the start of the pattern to the character where
-the error was discovered is placed in the variable pointed to by
+error message. This is a static string that is part of the library. You must
+not try to free it. The offset from the start of the pattern to the character
+where the error was discovered is placed in the variable pointed to by
\fIerroffset\fP, which must not be NULL. If it is, an immediate error is given.
.P
+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
+returned via this argument in the event of an error. This is in addition to the
+textual error message. Error codes and messages are listed below.
+.P
If the final argument, \fItableptr\fP, is NULL, PCRE uses a default set of
character tables that are built when PCRE is compiled, using the default C
locale. Otherwise, \fItableptr\fP must be an address that is the result of a
@@ -358,39 +468,64 @@
.\"
documentation.
.sp
+ PCRE_BSR_ANYCRLF
+ PCRE_BSR_UNICODE
+.sp
+These options (which are mutually exclusive) control what the \eR escape
+sequence matches. The choice is either to match only CR, LF, or CRLF, or to
+match any Unicode newline sequence. The default is specified when PCRE is
+built. It can be overridden from within the pattern, or by setting an option
+when a compiled pattern is matched.
+.sp
PCRE_CASELESS
.sp
If this bit is set, letters in the pattern match both upper and lower case
letters. It is equivalent to Perl's /i option, and it can be changed within a
-pattern by a (?i) option setting. When running in UTF-8 mode, case support for
-high-valued characters is available only when PCRE is built with Unicode
-character property support.
+pattern by a (?i) option setting. In UTF-8 mode, PCRE always understands the
+concept of case for characters whose values are less than 128, so caseless
+matching is always possible. For characters with higher values, the concept of
+case is supported if PCRE is compiled with Unicode property support, but not
+otherwise. If you want to use caseless matching for characters 128 and above,
+you must ensure that PCRE is compiled with Unicode property support as well as
+with UTF-8 support.
.sp
PCRE_DOLLAR_ENDONLY
.sp
If this bit is set, a dollar metacharacter in the pattern matches only at the
end of the subject string. Without this option, a dollar also matches
-immediately before the final character if it is a newline (but not before any
-other newlines). The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is
-set. There is no equivalent to this option in Perl, and no way to set it within
-a pattern.
+immediately before a newline at the end of the string (but not before any other
+newlines). The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is set.
+There is no equivalent to this option in Perl, and no way to set it within a
+pattern.
.sp
PCRE_DOTALL
.sp
If this bit is set, a dot metacharater in the pattern matches all characters,
-including newlines. Without it, newlines are excluded. This option is
-equivalent to Perl's /s option, and it can be changed within a pattern by a
-(?s) option setting. A negative class such as [^a] always matches a newline
-character, independent of the setting of this option.
+including those that indicate newline. Without it, a dot does not match when
+the current position is at a newline. This option is equivalent to Perl's /s
+option, and it can be changed within a pattern by a (?s) option setting. A
+negative class such as [^a] always matches newline characters, independent of
+the setting of this option.
+.sp
+ PCRE_DUPNAMES
+.sp
+If this bit is set, names used to identify capturing subpatterns need not be
+unique. This can be helpful for certain types of pattern when it is known that
+only one instance of the named subpattern can ever be matched. There are more
+details of named subpatterns below; see also the
+.\" HREF
+\fBpcrepattern\fP
+.\"
+documentation.
.sp
PCRE_EXTENDED
.sp
If this bit is set, whitespace data characters in the pattern are totally
ignored except when escaped or inside a character class. Whitespace does not
include the VT character (code 11). In addition, characters between an
-unescaped # outside a character class and the next newline character,
-inclusive, are also ignored. This is equivalent to Perl's /x option, and it can
-be changed within a pattern by a (?x) option setting.
+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
+pattern by a (?x) option setting.
.P
This option makes it possible to include comments inside complicated patterns.
Note, however, that this applies only to data characters. Whitespace characters
@@ -404,9 +539,15 @@
set, any backslash in a pattern that is followed by a letter that has no
special meaning causes an error, thus reserving these combinations for future
expansion. By default, as in Perl, a backslash followed by a letter with no
-special meaning is treated as a literal. There are at present no other features
-controlled by this option. It can also be set by a (?X) option setting within a
-pattern.
+special meaning is treated as a literal. (Perl can, however, be persuaded to
+give a warning for this.) There are at present no other features controlled by
+this option. It can also be set by a (?X) option setting within a pattern.
+.sp
+ PCRE_FIRSTLINE
+.sp
+If this option is set, an unanchored pattern is required to match before or at
+the first newline in the subject string, though the matched text may continue
+over the newline.
.sp
PCRE_MULTILINE
.sp
@@ -418,12 +559,47 @@
Perl.
.P
When PCRE_MULTILINE it is set, the "start of line" and "end of line" constructs
-match immediately following or immediately before any newline in the subject
-string, respectively, as well as at the very start and end. This is equivalent
-to Perl's /m option, and it can be changed within a pattern by a (?m) option
-setting. If there are no "\en" characters in a subject string, or no
+match immediately following or immediately before internal newlines in the
+subject string, respectively, as well as at the very start and end. This is
+equivalent to Perl's /m option, and it can be changed within a pattern by a
+(?m) option setting. If there are no newlines in a subject string, or no
occurrences of ^ or $ in a pattern, setting PCRE_MULTILINE has no effect.
.sp
+ PCRE_NEWLINE_CR
+ PCRE_NEWLINE_LF
+ PCRE_NEWLINE_CRLF
+ PCRE_NEWLINE_ANYCRLF
+ PCRE_NEWLINE_ANY
+.sp
+These options override the default newline definition that was chosen when PCRE
+was built. Setting the first or the second specifies that a newline is
+indicated by a single character (CR or LF, respectively). Setting
+PCRE_NEWLINE_CRLF specifies that a newline is indicated by the two-character
+CRLF sequence. Setting PCRE_NEWLINE_ANYCRLF specifies that any of the three
+preceding sequences should be recognized. Setting PCRE_NEWLINE_ANY specifies
+that any Unicode newline sequence should be recognized. The Unicode newline
+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
+separator, U+2028), and PS (paragraph separator, U+2029). The last two are
+recognized only in UTF-8 mode.
+.P
+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
+plus the five values above). This means that if you set more than one newline
+option, the combination may or may not be sensible. For example,
+PCRE_NEWLINE_CR with PCRE_NEWLINE_LF is equivalent to PCRE_NEWLINE_CRLF, but
+other combinations may yield unused numbers and cause an error.
+.P
+The only time that a line break is specially recognized when compiling a
+pattern is if PCRE_EXTENDED is set, and an unescaped # outside a character
+class is encountered. This indicates a comment that lasts until after the next
+line break sequence. In other circumstances, line break sequences are treated
+as literal data, except that in PCRE_EXTENDED mode, both CR and LF are treated
+as whitespace characters and are therefore ignored.
+.P
+The newline option that is set at compile time becomes the default that is used
+for \fBpcre_exec()\fP and \fBpcre_dfa_exec()\fP, but it can be overridden.
+.sp
PCRE_NO_AUTO_CAPTURE
.sp
If this option is set, it disables the use of numbered capturing parentheses in
@@ -458,19 +634,98 @@
PCRE_NO_UTF8_CHECK
.sp
When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string is
-automatically checked. If an invalid UTF-8 sequence of bytes is found,
-\fBpcre_compile()\fP returns an error. If you already know that your pattern is
-valid, and you want to skip this check for performance reasons, you can set the
-PCRE_NO_UTF8_CHECK option. When it is set, the effect of passing an invalid
-UTF-8 string as a pattern is undefined. It may cause your program to crash.
-Note that this option can also be passed to \fBpcre_exec()\fP, to suppress the
-UTF-8 validity checking of subject strings.
+automatically checked. There is a discussion about the
+.\" HTML <a href="pcre.html#utf8strings">
+.\" </a>
+validity of UTF-8 strings
+.\"
+in the main
+.\" HREF
+\fBpcre\fP
+.\"
+page. If an invalid UTF-8 sequence of bytes is found, \fBpcre_compile()\fP
+returns an error. If you already know that your pattern is valid, and you want
+to skip this check for performance reasons, you can set the PCRE_NO_UTF8_CHECK
+option. When it is set, the effect of passing an invalid UTF-8 string as a
+pattern is undefined. It may cause your program to crash. Note that this option
+can also be passed to \fBpcre_exec()\fP and \fBpcre_dfa_exec()\fP, to suppress
+the UTF-8 validity checking of subject strings.
+.
+.
+.SH "COMPILATION ERROR CODES"
+.rs
+.sp
+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
+both compiling functions. As PCRE has developed, some error codes have fallen
+out of use. To avoid confusion, they have not been re-used.
+.sp
+ 0 no error
+ 1 \e at end of pattern
+ 2 \ec at end of pattern
+ 3 unrecognized character follows \e
+ 4 numbers out of order in {} quantifier
+ 5 number too big in {} quantifier
+ 6 missing terminating ] for character class
+ 7 invalid escape sequence in character class
+ 8 range out of order in character class
+ 9 nothing to repeat
+ 10 [this code is not in use]
+ 11 internal error: unexpected repeat
+ 12 unrecognized character after (?
+ 13 POSIX named classes are supported only within a class
+ 14 missing )
+ 15 reference to non-existent subpattern
+ 16 erroffset passed as NULL
+ 17 unknown option bit(s) set
+ 18 missing ) after comment
+ 19 [this code is not in use]
+ 20 regular expression too large
+ 21 failed to get memory
+ 22 unmatched parentheses
+ 23 internal error: code overflow
+ 24 unrecognized character after (?<
+ 25 lookbehind assertion is not fixed length
+ 26 malformed number or name after (?(
+ 27 conditional group contains more than two branches
+ 28 assertion expected after (?(
+ 29 (?R or (?[+-]digits must be followed by )
+ 30 unknown POSIX class name
+ 31 POSIX collating elements are not supported
+ 32 this version of PCRE is not compiled with PCRE_UTF8 support
+ 33 [this code is not in use]
+ 34 character value in \ex{...} sequence is too large
+ 35 invalid condition (?(0)
+ 36 \eC not allowed in lookbehind assertion
+ 37 PCRE does not support \eL, \el, \eN, \eU, or \eu
+ 38 number after (?C is > 255
+ 39 closing ) for (?C expected
+ 40 recursive call could loop indefinitely
+ 41 unrecognized character after (?P
+ 42 syntax error in subpattern name (missing terminator)
+ 43 two named subpatterns have the same name
+ 44 invalid UTF-8 string
+ 45 support for \eP, \ep, and \eX has not been compiled
+ 46 malformed \eP or \ep sequence
+ 47 unknown property name after \eP or \ep
+ 48 subpattern name is too long (maximum 32 characters)
+ 49 too many named subpatterns (maximum 10,000)
+ 50 [this code is not in use]
+ 51 octal value is greater than \e377 (not in UTF-8 mode)
+ 52 internal error: overran compiling workspace
+ 53 internal error: previously-checked referenced subpattern not found
+ 54 DEFINE group contains more than one branch
+ 55 repeating a DEFINE group is not allowed
+ 56 inconsistent NEWLINE options
+ 57 \eg is not followed by a braced name or an optionally braced
+ non-zero number
+ 58 (?+ or (?- or (?(+ or (?(- must be followed by a non-zero number
.
.
.SH "STUDYING A PATTERN"
.rs
.sp
-.B pcre_extra *pcre_study(const pcre *\fIcode\fP, int \fIoptions\fP,
+.B pcre_extra *pcre_study(const pcre *\fIcode\fP, int \fIoptions\fP
.ti +5n
.B const char **\fIerrptr\fP);
.PP
@@ -492,7 +747,7 @@
.\"
in the section on matching a pattern.
.P
-If studying the pattern does not produce any additional information,
+If studying the pattern does not produce any additional information
\fBpcre_study()\fP returns NULL. In that circumstance, if the calling program
wants to pass any of the other fields to \fBpcre_exec()\fP, it must set up its
own \fBpcre_extra\fP block.
@@ -502,9 +757,10 @@
.P
The third argument for \fBpcre_study()\fP is a pointer for an error message. If
studying succeeds (even if no data is returned), the variable it points to is
-set to NULL. Otherwise it points to a textual error message. You should
-therefore test the error pointer for NULL after calling \fBpcre_study()\fP, to
-be sure that it has run successfully.
+set to NULL. Otherwise it is set to point to a textual error message. This is a
+static string that is part of the library. You must not try to free it. You
+should test the error pointer for NULL after calling \fBpcre_study()\fP, to be
+sure that it has run successfully.
.P
This is a typical call to \fBpcre_study\fP():
.sp
@@ -525,17 +781,23 @@
.sp
PCRE handles caseless matching, and determines whether characters are letters,
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 with codes
less than 128. Higher-valued codes never match escapes such as \ew or \ed, but
can be tested with \ep if PCRE is built with Unicode character property
-support.)
-.P
-An internal set of tables is created in the default C locale when PCRE is
-built. This is used when the final argument of \fBpcre_compile()\fP is NULL,
-and is sufficient for many applications. An alternative set of tables can,
-however, be supplied. These may be created in a different locale from the
-default. As more and more applications change to using Unicode, the need for
-this locale support is expected to die away.
+support. The use of locales with Unicode is discouraged. If you are handling
+characters with codes greater than 128, you should either use UTF-8 and
+Unicode, or use locales, but not try to mix the two.
+.P
+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.
+Normally, the internal tables recognize only ASCII characters. However, when
+PCRE is built, it is possible to cause the internal tables to be rebuilt in the
+default "C" locale of the local system, which may cause them to be different.
+.P
+The internal tables can always be overridden by tables supplied by the
+application that calls PCRE. These may be created in a different locale from
+the default. As more and more applications change to using Unicode, the need
+for this locale support is expected to die away.
.P
External tables are built by calling the \fBpcre_maketables()\fP function,
which has no arguments, in the relevant locale. The result can then be passed
@@ -548,6 +810,9 @@
tables = pcre_maketables();
re = pcre_compile(..., tables);
.sp
+The locale name "fr_FR" is used on Linux and other Unix-like systems; if you
+are using Windows, the name for the French locale is "french".
+.P
When \fBpcre_maketables()\fP runs, the tables are built in memory that is
obtained via \fBpcre_malloc\fP. It is the caller's responsibility to ensure
that the memory containing the tables remains available for as long as it is
@@ -594,7 +859,7 @@
\fBpcre_fullinfo()\fP, to obtain the length of the compiled pattern:
.sp
int rc;
- unsigned long int length;
+ size_t length;
rc = pcre_fullinfo(
re, /* result of pcre_compile() */
pe, /* result of pcre_study(), or NULL */
@@ -615,7 +880,7 @@
Return the number of capturing subpatterns in the pattern. The fourth argument
should point to an \fBint\fP variable.
.sp
- PCRE_INFO_DEFAULTTABLES
+ PCRE_INFO_DEFAULT_TABLES
.sp
Return a pointer to the internal default character tables within PCRE. The
fourth argument should point to an \fBunsigned char *\fP variable. This
@@ -626,12 +891,12 @@
PCRE_INFO_FIRSTBYTE
.sp
Return information about the first byte of any matched string, for a
-non-anchored pattern. (This option used to be called PCRE_INFO_FIRSTCHAR; the
-old name is still recognized for backwards compatibility.)
+non-anchored pattern. The fourth argument should point to an \fBint\fP
+variable. (This option used to be called PCRE_INFO_FIRSTCHAR; the old name is
+still recognized for backwards compatibility.)
.P
If there is a fixed first byte, for example, from a pattern such as
-(cat|cow|coyote), it is returned in the integer pointed to by \fIwhere\fP.
-Otherwise, if either
+(cat|cow|coyote), its value is returned. Otherwise, if either
.sp
(a) the pattern was compiled with the PCRE_MULTILINE option, and every branch
starts with "^", or
@@ -650,6 +915,18 @@
string, a pointer to the table is returned. Otherwise NULL is returned. The
fourth argument should point to an \fBunsigned char *\fP variable.
.sp
+ PCRE_INFO_HASCRORLF
+.sp
+Return 1 if the pattern contains any explicit matches for CR or LF characters,
+otherwise 0. The fourth argument should point to an \fBint\fP variable. An
+explicit match is either a literal CR or LF character, or \er or \en.
+.sp
+ PCRE_INFO_JCHANGED
+.sp
+Return 1 if the (?J) option setting is used in the pattern, otherwise 0. The
+fourth argument should point to an \fBint\fP variable. The (?J) internal option
+setting changes the local PCRE_DUPNAMES option.
+.sp
PCRE_INFO_LASTLITERAL
.sp
Return the value of the rightmost literal byte that must exist in any matched
@@ -666,12 +943,13 @@
.sp
PCRE supports the use of named as well as numbered capturing parentheses. The
names are just an additional way of identifying the parentheses, which still
-acquire numbers. A convenience function called \fBpcre_get_named_substring()\fP
-is provided for extracting an individual captured substring by name. It is also
-possible to extract the data directly, by first converting the name to a number
-in order to access the correct pointers in the output vector (described with
-\fBpcre_exec()\fP below). To do the conversion, you need to use the
-name-to-number map, which is described by these three values.
+acquire numbers. Several convenience functions such as
+\fBpcre_get_named_substring()\fP are provided for extracting captured
+substrings by name. It is also possible to extract the data directly, by first
+converting the name to a number in order to access the correct pointers in the
+output vector (described with \fBpcre_exec()\fP below). To do the conversion,
+you need to use the name-to-number map, which is described by these three
+values.
.P
The map consists of a number of fixed-size entries. PCRE_INFO_NAMECOUNT gives
the number of entries, and PCRE_INFO_NAMEENTRYSIZE gives the size of each
@@ -680,12 +958,13 @@
entry of the table (a pointer to \fBchar\fP). The first two bytes of each entry
are the number of the capturing parenthesis, most significant byte first. The
rest of the entry is the corresponding name, zero terminated. The names are in
-alphabetical order. For example, consider the following pattern (assume
+alphabetical order. When PCRE_DUPNAMES is set, duplicate names are in order of
+their parentheses numbers. For example, consider the following pattern (assume
PCRE_EXTENDED is set, so white space - including newlines - is ignored):
.sp
.\" JOIN
- (?P<date> (?P<year>(\ed\ed)?\ed\ed) -
- (?P<month>\ed\ed) - (?P<day>\ed\ed) )
+ (?<date> (?<year>(\ed\ed)?\ed\ed) -
+ (?<month>\ed\ed) - (?<day>\ed\ed) )
.sp
There are four named subpatterns, so the table has four entries, and each entry
in the table is eight bytes long. The table is as follows, with non-printing
@@ -697,15 +976,28 @@
00 02 y e a r 00 ??
.sp
When writing code to extract data from named subpatterns using the
-name-to-number map, remember that the length of each entry is likely to be
+name-to-number map, remember that the length of the entries is likely to be
different for each compiled pattern.
.sp
+ PCRE_INFO_OKPARTIAL
+.sp
+Return 1 if the pattern can be used for partial matching, otherwise 0. The
+fourth argument should point to an \fBint\fP variable. The
+.\" HREF
+\fBpcrepartial\fP
+.\"
+documentation lists the restrictions that apply to patterns when partial
+matching is used.
+.sp
PCRE_INFO_OPTIONS
.sp
Return a copy of the options with which the pattern was compiled. The fourth
argument should point to an \fBunsigned long int\fP variable. These option bits
are those specified in the call to \fBpcre_compile()\fP, modified by any
-top-level option settings within the pattern itself.
+top-level option settings at the start of the pattern itself. In other words,
+they are the options that will be in force when matching starts. For example,
+if the pattern /(?im)abc(?-i)d/ is compiled with the PCRE_EXTENDED option, the
+result is PCRE_CASELESS, PCRE_MULTILINE, and PCRE_EXTENDED.
.P
A pattern is automatically anchored by PCRE if all of its top-level
alternatives begin with one of the following:
@@ -760,7 +1052,30 @@
string (see PCRE_INFO_FIRSTBYTE above).
.
.
-.SH "MATCHING A PATTERN"
+.SH "REFERENCE COUNTS"
+.rs
+.sp
+.B int pcre_refcount(pcre *\fIcode\fP, int \fIadjust\fP);
+.PP
+The \fBpcre_refcount()\fP function is used to maintain a reference count in the
+data block that contains a compiled pattern. It is provided for the benefit of
+applications that operate in an object-oriented manner, where different parts
+of the application may be using the same compiled pattern, but you want to free
+the block when they are all done.
+.P
+When a pattern is compiled, the reference count field is initialized to zero.
+It is changed only by calling this function, whose action is to add the
+\fIadjust\fP value (which may be positive or negative) to it. The yield of the
+function is the new value. However, the value of the count is constrained to
+lie between 0 and 65535, inclusive. If the new value is outside these limits,
+it is forced to the appropriate limit value.
+.P
+Except when it is zero, the reference count is not correctly preserved if a
+pattern is compiled on one host and then transferred to a host whose byte-order
+is different. (This seems a highly unlikely scenario.)
+.
+.
+.SH "MATCHING A PATTERN: THE TRADITIONAL FUNCTION"
.rs
.sp
.B int pcre_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP,"
@@ -772,7 +1087,14 @@
The function \fBpcre_exec()\fP is called to match a subject string against a
compiled pattern, which is passed in the \fIcode\fP argument. If the
pattern has been studied, the result of the study should be passed in the
-\fIextra\fP argument.
+\fIextra\fP argument. This function is the main matching facility of the
+library, and it operates in a Perl-like manner. For specialist use there is
+also an alternative matching function, which is described
+.\" HTML <a href="#dfamatch">
+.\" </a>
+below
+.\"
+in the section about the \fBpcre_dfa_exec()\fP function.
.P
In most applications, the pattern will have been compiled (and optionally
studied) in the same process that calls \fBpcre_exec()\fP. However, it is
@@ -796,7 +1118,7 @@
0, /* start at offset 0 in the subject */
0, /* default options */
ovector, /* vector of integers for substring information */
- 30); /* number of elements in the vector (NOT size in bytes) */
+ 30); /* number of elements (NOT size in bytes) */
.
.\" HTML <a name="extradata"></a>
.SS "Extra data for \fBpcre_exec()\fR"
@@ -805,12 +1127,13 @@
If the \fIextra\fP argument is not NULL, it must point to a \fBpcre_extra\fP
data block. The \fBpcre_study()\fP function returns such a block (when it
doesn't return NULL), but you can also create one for yourself, and pass
-additional information in it. The fields in a \fBpcre_extra\fP block are as
-follows:
+additional information in it. The \fBpcre_extra\fP block contains the following
+fields (not necessarily in this order):
.sp
unsigned long int \fIflags\fP;
void *\fIstudy_data\fP;
unsigned long int \fImatch_limit\fP;
+ unsigned long int \fImatch_limit_recursion\fP;
void *\fIcallout_data\fP;
const unsigned char *\fItables\fP;
.sp
@@ -819,6 +1142,7 @@
.sp
PCRE_EXTRA_STUDY_DATA
PCRE_EXTRA_MATCH_LIMIT
+ PCRE_EXTRA_MATCH_LIMIT_RECURSION
PCRE_EXTRA_CALLOUT_DATA
PCRE_EXTRA_TABLES
.sp
@@ -833,17 +1157,35 @@
classic example is the use of nested unlimited repeats.
.P
Internally, PCRE uses a function called \fBmatch()\fP which it calls repeatedly
-(sometimes recursively). The limit is imposed on the number of times this
-function is called during a match, which has the effect of limiting the amount
-of recursion and backtracking that can take place. For patterns that are not
-anchored, the count starts from zero for each position in the subject string.
+(sometimes recursively). The limit set by \fImatch_limit\fP is imposed on the
+number of times this function is called during a match, which has the effect of
+limiting the amount of backtracking that can take place. For patterns that are
+not anchored, the count restarts from zero for each position in the subject
+string.
.P
-The default limit for the library 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
-reduce the default by suppling \fBpcre_exec()\fP with a \fBpcre_extra\fP block
-in which \fImatch_limit\fP is set to a smaller value, and
-PCRE_EXTRA_MATCH_LIMIT is set in the \fIflags\fP field. If the limit is
-exceeded, \fBpcre_exec()\fP returns PCRE_ERROR_MATCHLIMIT.
+override the default by suppling \fBpcre_exec()\fP with a \fBpcre_extra\fP
+block in which \fImatch_limit\fP is set, and PCRE_EXTRA_MATCH_LIMIT is set in
+the \fIflags\fP field. If the limit is exceeded, \fBpcre_exec()\fP returns
+PCRE_ERROR_MATCHLIMIT.
+.P
+The \fImatch_limit_recursion\fP field is similar to \fImatch_limit\fP, but
+instead of limiting the total number of times that \fBmatch()\fP is called, it
+limits the depth of recursion. The recursion depth is a smaller number than the
+total number of calls, because not all calls to \fBmatch()\fP are recursive.
+This limit is of use only if it is set smaller than \fImatch_limit\fP.
+.P
+Limiting the recursion depth limits the amount of stack that can be 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.
+.P
+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
+\fImatch_limit\fP. You can override the default by suppling \fBpcre_exec()\fP
+with a \fBpcre_extra\fP block in which \fImatch_limit_recursion\fP is set, and
+PCRE_EXTRA_MATCH_LIMIT_RECURSION is set in the \fIflags\fP field. If the limit
+is exceeded, \fBpcre_exec()\fP returns PCRE_ERROR_RECURSIONLIMIT.
.P
The \fIpcre_callout\fP field is used in conjunction with the "callout" feature,
which is described in the
@@ -866,12 +1208,13 @@
.\"
documentation for a discussion of saving compiled patterns for later use.
.
+.\" HTML <a name="execoptions"></a>
.SS "Option bits for \fBpcre_exec()\fP"
.rs
.sp
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_NOTBOL,
-PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NO_UTF8_CHECK and PCRE_PARTIAL.
+zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_\fIxxx\fP,
+PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NO_UTF8_CHECK and PCRE_PARTIAL.
.sp
PCRE_ANCHORED
.sp
@@ -880,6 +1223,48 @@
to be anchored by virtue of its contents, it cannot be made unachored at
matching time.
.sp
+ PCRE_BSR_ANYCRLF
+ PCRE_BSR_UNICODE
+.sp
+These options (which are mutually exclusive) control what the \eR escape
+sequence matches. The choice is either to match only CR, LF, or CRLF, or to
+match any Unicode newline sequence. These options override the choice that was
+made or defaulted when the pattern was compiled.
+.sp
+ PCRE_NEWLINE_CR
+ PCRE_NEWLINE_LF
+ PCRE_NEWLINE_CRLF
+ PCRE_NEWLINE_ANYCRLF
+ PCRE_NEWLINE_ANY
+.sp
+These options override the newline definition that was chosen or defaulted when
+the pattern was compiled. For details, see the description of
+\fBpcre_compile()\fP above. During matching, the newline choice affects the
+behaviour of the dot, circumflex, and dollar metacharacters. It may also alter
+the way the match position is advanced after a match failure for an unanchored
+pattern.
+.P
+When PCRE_NEWLINE_CRLF, PCRE_NEWLINE_ANYCRLF, or PCRE_NEWLINE_ANY is set, and a
+match attempt for an unanchored pattern fails when the current position is at a
+CRLF sequence, and the pattern contains no explicit matches for CR or LF
+characters, the match position is advanced by two characters instead of one, in
+other words, to after the CRLF.
+.P
+The above rule is a compromise that makes the most common cases work as
+expected. For example, if the pattern is .+A (and the PCRE_DOTALL option is not
+set), it does not match the string "\er\enA" because, after failing at the
+start, it skips both the CR and the LF before retrying. However, the pattern
+[\er\en]A does match that string, because it contains an explicit CR or LF
+reference, and so advances only by one character after the first failure.
+.P
+An explicit match for CR of LF is either a literal appearance of one of those
+characters, or one of the \er or \en escape sequences. Implicit matches such as
+[^X] do not count, nor does \es (which includes CR and LF in the characters
+that it matches).
+.P
+Notwithstanding the above, anomalous effects may still occur when CRLF is a
+valid newline sequence and explicit \er or \en escapes appear in the pattern.
+.sp
PCRE_NOTBOL
.sp
This option specifies that first character of the subject string is not the
@@ -921,9 +1306,19 @@
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.
The value of \fIstartoffset\fP is also checked to ensure that it points to the
-start of a UTF-8 character. If an invalid UTF-8 sequence of bytes is found,
-\fBpcre_exec()\fP returns the error PCRE_ERROR_BADUTF8. If \fIstartoffset\fP
-contains an invalid value, PCRE_ERROR_BADUTF8_OFFSET is returned.
+start of a UTF-8 character. There is a discussion about the validity of UTF-8
+strings in the
+.\" HTML <a href="pcre.html#utf8strings">
+.\" </a>
+section on UTF-8 support
+.\"
+in the main
+.\" HREF
+\fBpcre\fP
+.\"
+page. If an invalid UTF-8 sequence of bytes is found, \fBpcre_exec()\fP returns
+the error PCRE_ERROR_BADUTF8. If \fIstartoffset\fP contains an invalid value,
+PCRE_ERROR_BADUTF8_OFFSET is returned.
.P
If you already know that your subject is valid, and you want to skip these
checks for performance reasons, you can set the PCRE_NO_UTF8_CHECK option when
@@ -1011,18 +1406,10 @@
first pair, \fIovector[0]\fP and \fIovector[1]\fP, identify the portion of the
subject string matched by the entire pattern. The next pair is used for the
first capturing subpattern, and so on. The value returned by \fBpcre_exec()\fP
-is the number of pairs that have been set. If there are no capturing
-subpatterns, the return value from a successful match is 1, indicating that
-just the first pair of offsets has been set.
-.P
-Some convenience functions are provided for extracting the captured substrings
-as separate strings. These are described in the following section.
-.P
-It is possible for an capturing subpattern number \fIn+1\fP to match some
-part of the subject when subpattern \fIn\fP has not been used at all. For
-example, if the string "abc" is matched against the pattern (a|(z))(bc)
-subpatterns 1 and 3 are matched, but 2 is not. When this happens, both offset
-values corresponding to the unused subpattern are set to -1.
+is one more than the highest numbered pair that has been set. For example, if
+two substrings have been captured, the returned value is 3. If there are no
+capturing subpatterns, the return value from a successful match is 1,
+indicating that just the first pair of offsets has been set.
.P
If a capturing subpattern is matched repeatedly, it is the last portion of the
string that it matched that is returned.
@@ -1036,12 +1423,31 @@
has to get additional memory for use during matching. Thus it is usually
advisable to supply an \fIovector\fP.
.P
-Note that \fBpcre_info()\fP can be used to find out how many capturing
+The \fBpcre_info()\fP function can be used to find out how many capturing
subpatterns there are in a compiled pattern. The smallest size for
\fIovector\fP that will allow for \fIn\fP captured substrings, in addition to
the offsets of the substring matched by the whole pattern, is (\fIn\fP+1)*3.
+.P
+It is possible for capturing subpattern number \fIn+1\fP to match some part of
+the subject when subpattern \fIn\fP has not been used at all. For example, if
+the string "abc" is matched against the pattern (a|(z))(bc) the return from the
+function is 4, and subpatterns 1 and 3 are matched, but 2 is not. When this
+happens, both values in the offset pairs corresponding to unused subpatterns
+are set to -1.
+.P
+Offset values that correspond to unused subpatterns at the end of the
+expression are also set to -1. For example, if the string "abc" is matched
+against the pattern (abc)(x(yz)?)? subpatterns 2 and 3 are not matched. The
+return from the function is 2, because the highest used capturing subpattern
+number is 1. However, you can refer to the offsets for the second and third
+capturing subpatterns if you wish (assuming the vector is large enough, of
+course).
+.P
+Some convenience functions are provided for extracting the captured substrings
+as separate strings. These are described below.
.
-.SS "Return values from \fBpcre_exec()\fP"
+.\" HTML <a name="errorlist"></a>
+.SS "Error return values from \fBpcre_exec()\fP"
.rs
.sp
If \fBpcre_exec()\fP fails, it returns a negative number. The following are
@@ -1068,7 +1474,7 @@
other endianness. This is the error that PCRE gives when the magic number is
not present.
.sp
- PCRE_ERROR_UNKNOWN_NODE (-5)
+ PCRE_ERROR_UNKNOWN_OPCODE (-5)
.sp
While running the pattern match, an unknown item was encountered in the
compiled pattern. This error could be caused by a bug in PCRE or by overwriting
@@ -1090,9 +1496,9 @@
.sp
PCRE_ERROR_MATCHLIMIT (-8)
.sp
-The recursion and backtracking limit, as specified by the \fImatch_limit\fP
-field in a \fBpcre_extra\fP structure (or defaulted) was reached. See the
-description above.
+The backtracking limit, as specified by the \fImatch_limit\fP field in a
+\fBpcre_extra\fP structure (or defaulted) was reached. See the description
+above.
.sp
PCRE_ERROR_CALLOUT (-9)
.sp
@@ -1112,7 +1518,7 @@
The UTF-8 byte sequence that was passed as a subject was valid, but the value
of \fIstartoffset\fP did not point to the beginning of a UTF-8 character.
.sp
- PCRE_ERROR_PARTIAL (-12)
+ PCRE_ERROR_PARTIAL (-12)
.sp
The subject string did not match, but it did match partially. See the
.\" HREF
@@ -1120,7 +1526,7 @@
.\"
documentation for details of partial matching.
.sp
- PCRE_ERROR_BAD_PARTIAL (-13)
+ PCRE_ERROR_BADPARTIAL (-13)
.sp
The PCRE_PARTIAL option was used with a compiled pattern containing items that
are not supported for partial matching. See the
@@ -1129,14 +1535,26 @@
.\"
documentation for details of partial matching.
.sp
- PCRE_ERROR_INTERNAL (-14)
+ PCRE_ERROR_INTERNAL (-14)
.sp
An unexpected internal error has occurred. This error could be caused by a bug
in PCRE or by overwriting of the compiled pattern.
.sp
- PCRE_ERROR_BADCOUNT (-15)
+ PCRE_ERROR_BADCOUNT (-15)
.sp
This error is given if the value of the \fIovecsize\fP argument is negative.
+.sp
+ PCRE_ERROR_RECURSIONLIMIT (-21)
+.sp
+The internal recursion limit, as specified by the \fImatch_limit_recursion\fP
+field in a \fBpcre_extra\fP structure (or defaulted) was reached. See the
+description above.
+.sp
+ PCRE_ERROR_BADNEWLINE (-23)
+.sp
+An invalid combination of PCRE_NEWLINE_\fIxxx\fP options was given.
+.P
+Error numbers -16 to -20 and -22 are not used by \fBpcre_exec()\fP.
.
.
.SH "EXTRACTING CAPTURED SUBSTRINGS BY NUMBER"
@@ -1148,14 +1566,12 @@
.ti +5n
.B int \fIbuffersize\fP);
.PP
-.br
.B int pcre_get_substring(const char *\fIsubject\fP, int *\fIovector\fP,
.ti +5n
.B int \fIstringcount\fP, int \fIstringnumber\fP,
.ti +5n
.B const char **\fIstringptr\fP);
.PP
-.br
.B int pcre_get_substring_list(const char *\fIsubject\fP,
.ti +5n
.B int *\fIovector\fP, int \fIstringcount\fP, "const char ***\fIlistptr\fP);"
@@ -1166,9 +1582,15 @@
\fBpcre_get_substring_list()\fP are provided for extracting captured substrings
as new, separate, zero-terminated strings. These functions identify substrings
by number. The next section describes functions for extracting named
-substrings. A substring that contains a binary zero is correctly extracted and
-has a further zero added on the end, but the result is not, of course,
-a C string.
+substrings.
+.P
+A substring that contains a binary zero is correctly extracted and has a
+further zero added on the end, but the result is not, of course, a C string.
+However, you can process such a string by referring to the length that is
+returned by \fBpcre_copy_substring()\fP and \fBpcre_get_substring()\fP.
+Unfortunately, the interface to \fBpcre_get_substring_list()\fP is not adequate
+for handling strings containing binary zeros, because the end of the final
+string is not independently indicated.
.P
The first three arguments are the same for all three of these functions:
\fIsubject\fP is the subject string that has just been successfully matched,
@@ -1188,7 +1610,7 @@
\fIbuffersize\fP, while for \fBpcre_get_substring()\fP a new block of memory is
obtained via \fBpcre_malloc\fP, and its address is returned via
\fIstringptr\fP. The yield of the function is the length of the string, not
-including the terminating zero, or one of
+including the terminating zero, or one of these error codes:
.sp
PCRE_ERROR_NOMEMORY (-6)
.sp
@@ -1204,7 +1626,7 @@
memory that is obtained via \fBpcre_malloc\fP. The address of the memory block
is returned via \fIlistptr\fP, which is also the start of the list of string
pointers. The end of the list is marked by a NULL pointer. The yield of the
-function is zero if all went well, or
+function is zero if all went well, or the error code
.sp
PCRE_ERROR_NOMEMORY (-6)
.sp
@@ -1223,7 +1645,7 @@
\fBpcre_get_substring_list()\fP, respectively. They do nothing more than call
the function pointed to by \fBpcre_free\fP, which of course could be called
directly from a C program. However, PCRE is used in some situations where it is
-linked via a special interface to another programming language which cannot use
+linked via a special interface to another programming language that cannot use
\fBpcre_free\fP directly; it is for these cases that the functions are
provided.
.
@@ -1235,7 +1657,6 @@
.ti +5n
.B const char *\fIname\fP);
.PP
-.br
.B int pcre_copy_named_substring(const pcre *\fIcode\fP,
.ti +5n
.B const char *\fIsubject\fP, int *\fIovector\fP,
@@ -1244,7 +1665,6 @@
.ti +5n
.B char *\fIbuffer\fP, int \fIbuffersize\fP);
.PP
-.br
.B int pcre_get_named_substring(const pcre *\fIcode\fP,
.ti +5n
.B const char *\fIsubject\fP, int *\fIovector\fP,
@@ -1258,9 +1678,10 @@
.sp
(a+)b(?<xxx>\ed+)...
.sp
-the number of the subpattern called "xxx" is 2. You can find the number from
-the name by calling \fBpcre_get_stringnumber()\fP. The first argument is the
-compiled pattern, and the second is the name. The yield of the function is the
+the number of the subpattern called "xxx" is 2. If the name is known to be
+unique (PCRE_DUPNAMES was not set), you can find the number from the name by
+calling \fBpcre_get_stringnumber()\fP. The first argument is the compiled
+pattern, and the second is the name. The yield of the function is the
subpattern number, or PCRE_ERROR_NOSUBSTRING (-7) if there is no subpattern of
that name.
.P
@@ -1268,8 +1689,8 @@
functions described in the previous section. For convenience, there are also
two functions that do the whole job.
.P
-Most of the arguments of \fIpcre_copy_named_substring()\fP and
-\fIpcre_get_named_substring()\fP are the same as those for the similarly named
+Most of the arguments of \fBpcre_copy_named_substring()\fP and
+\fBpcre_get_named_substring()\fP are the same as those for the similarly named
functions that extract by number. As these are described in the previous
section, they are not re-described here. There are just two differences:
.P
@@ -1279,10 +1700,258 @@
translation table.
.P
These functions call \fBpcre_get_stringnumber()\fP, and if it succeeds, they
-then call \fIpcre_copy_substring()\fP or \fIpcre_get_substring()\fP, as
-appropriate.
+then call \fBpcre_copy_substring()\fP or \fBpcre_get_substring()\fP, as
+appropriate. \fBNOTE:\fP If PCRE_DUPNAMES is set and there are duplicate names,
+the behaviour may not be what you want (see the next section).
+.
+.
+.SH "DUPLICATE SUBPATTERN NAMES"
+.rs
+.sp
+.B int pcre_get_stringtable_entries(const pcre *\fIcode\fP,
+.ti +5n
+.B const char *\fIname\fP, char **\fIfirst\fP, char **\fIlast\fP);
+.PP
+When a pattern is compiled with the PCRE_DUPNAMES option, names for subpatterns
+are not required to be unique. Normally, patterns with duplicate names are such
+that in any one match, only one of the named subpatterns participates. An
+example is shown in the
+.\" HREF
+\fBpcrepattern\fP
+.\"
+documentation.
.P
-.in 0
-Last updated: 09 September 2004
-.br
-Copyright (c) 1997-2004 University of Cambridge.
+When duplicates are present, \fBpcre_copy_named_substring()\fP and
+\fBpcre_get_named_substring()\fP return the first substring corresponding to
+the given name that is set. If none are set, PCRE_ERROR_NOSUBSTRING (-7) is
+returned; no data is returned. The \fBpcre_get_stringnumber()\fP function
+returns one of the numbers that are associated with the name, but it is not
+defined which it is.
+.P
+If you want to get full details of all captured substrings for a given name,
+you must use the \fBpcre_get_stringtable_entries()\fP function. The first
+argument is the compiled pattern, and the second is the name. The third and
+fourth are pointers to variables which are updated by the function. After it
+has run, they point to the first and last entries in the name-to-number table
+for the given name. The function itself returns the length of each entry, or
+PCRE_ERROR_NOSUBSTRING (-7) if there are none. The format of the table is
+described above in the section entitled \fIInformation about a pattern\fP.
+Given all the relevant entries for the name, you can extract each of their
+numbers, and hence the captured data, if any.
+.
+.
+.SH "FINDING ALL POSSIBLE MATCHES"
+.rs
+.sp
+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
+want to find all possible matches, or the longest possible match, consider
+using the alternative matching function (see below) instead. If you cannot use
+the alternative function, but still need to find all possible matches, you
+can kludge it up by making use of the callout facility, which is described in
+the
+.\" HREF
+\fBpcrecallout\fP
+.\"
+documentation.
+.P
+What you have to do is to insert a callout right at the end of the pattern.
+When your callout function is called, extract and save the current matched
+substring. Then return 1, which forces \fBpcre_exec()\fP to backtrack and try
+other alternatives. Ultimately, when it runs out of matches, \fBpcre_exec()\fP
+will yield PCRE_ERROR_NOMATCH.
+.
+.
+.\" HTML <a name="dfamatch"></a>
+.SH "MATCHING A PATTERN: THE ALTERNATIVE FUNCTION"
+.rs
+.sp
+.B int pcre_dfa_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP,"
+.ti +5n
+.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP,
+.ti +5n
+.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP,
+.ti +5n
+.B int *\fIworkspace\fP, int \fIwscount\fP);
+.P
+The function \fBpcre_dfa_exec()\fP is called to match a subject string against
+a compiled pattern, using a matching algorithm that scans the subject string
+just once, and does not backtrack. This has different characteristics to the
+normal algorithm, and is not compatible with Perl. Some of the features of PCRE
+patterns are not supported. Nevertheless, there are times when this kind of
+matching can be useful. For a discussion of the two matching algorithms, see
+the
+.\" HREF
+\fBpcrematching\fP
+.\"
+documentation.
+.P
+The arguments for the \fBpcre_dfa_exec()\fP function are the same as for
+\fBpcre_exec()\fP, plus two extras. The \fIovector\fP argument is used in a
+different way, and this is described below. The other common arguments are used
+in the same way as for \fBpcre_exec()\fP, so their description is not repeated
+here.
+.P
+The two additional arguments provide workspace for the function. The workspace
+vector should contain at least 20 elements. It is used for keeping track of
+multiple paths through the pattern tree. More workspace will be needed for
+patterns and subjects where there are a lot of potential matches.
+.P
+Here is an example of a simple call to \fBpcre_dfa_exec()\fP:
+.sp
+ int rc;
+ int ovector[10];
+ int wspace[20];
+ rc = pcre_dfa_exec(
+ re, /* result of pcre_compile() */
+ NULL, /* we didn't study the pattern */
+ "some string", /* the subject string */
+ 11, /* the length of the subject string */
+ 0, /* start at offset 0 in the subject */
+ 0, /* default options */
+ ovector, /* vector of integers for substring information */
+ 10, /* number of elements (NOT size in bytes) */
+ wspace, /* working space vector */
+ 20); /* number of elements (NOT size in bytes) */
+.
+.SS "Option bits for \fBpcre_dfa_exec()\fP"
+.rs
+.sp
+The unused bits of the \fIoptions\fP argument for \fBpcre_dfa_exec()\fP must be
+zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_\fIxxx\fP,
+PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NO_UTF8_CHECK, PCRE_PARTIAL,
+PCRE_DFA_SHORTEST, and PCRE_DFA_RESTART. All but the last three of these are
+the same as for \fBpcre_exec()\fP, so their description is not repeated here.
+.sp
+ PCRE_PARTIAL
+.sp
+This has the same general effect as it does for \fBpcre_exec()\fP, but the
+details are slightly different. When PCRE_PARTIAL is set for
+\fBpcre_dfa_exec()\fP, the return code PCRE_ERROR_NOMATCH is converted into
+PCRE_ERROR_PARTIAL if the end of the subject is reached, there have been no
+complete matches, but there is still at least one matching possibility. The
+portion of the string that provided the partial match is set as the first
+matching string.
+.sp
+ PCRE_DFA_SHORTEST
+.sp
+Setting the PCRE_DFA_SHORTEST option causes the matching algorithm to stop as
+soon as it has found one match. Because of the way the alternative algorithm
+works, this is necessarily the shortest possible match at the first possible
+matching point in the subject string.
+.sp
+ PCRE_DFA_RESTART
+.sp
+When \fBpcre_dfa_exec()\fP is called with the PCRE_PARTIAL option, and returns
+a partial match, it is possible to call it again, with additional subject
+characters, and have it continue with the same match. The PCRE_DFA_RESTART
+option requests this action; when it is set, the \fIworkspace\fP and
+\fIwscount\fP options must reference the same vector as before because data
+about the match so far is left in them after a partial match. There is more
+discussion of this facility in the
+.\" HREF
+\fBpcrepartial\fP
+.\"
+documentation.
+.
+.SS "Successful returns from \fBpcre_dfa_exec()\fP"
+.rs
+.sp
+When \fBpcre_dfa_exec()\fP succeeds, it may have matched more than one
+substring in the subject. Note, however, that all the matches from one run of
+the function start at the same point in the subject. The shorter matches are
+all initial substrings of the longer matches. For example, if the pattern
+.sp
+ <.*>
+.sp
+is matched against the string
+.sp
+ This is <something> <something else> <something further> no more
+.sp
+the three matched strings are
+.sp
+ <something>
+ <something> <something else>
+ <something> <something else> <something further>
+.sp
+On success, the yield of the function is a number greater than zero, which is
+the number of matched substrings. The substrings themselves are returned in
+\fIovector\fP. Each string uses two elements; the first is the offset to the
+start, and the second is the offset to the end. In fact, all the strings have
+the same start offset. (Space could have been saved by giving this only once,
+but it was decided to retain some compatibility with the way \fBpcre_exec()\fP
+returns data, even though the meaning of the strings is different.)
+.P
+The strings are returned in reverse order of length; that is, the longest
+matching string is given first. If there were too many matches to fit into
+\fIovector\fP, the yield of the function is zero, and the vector is filled with
+the longest matches.
+.
+.SS "Error returns from \fBpcre_dfa_exec()\fP"
+.rs
+.sp
+The \fBpcre_dfa_exec()\fP function returns a negative number when it fails.
+Many of the errors are the same as for \fBpcre_exec()\fP, and these are
+described
+.\" HTML <a href="#errorlist">
+.\" </a>
+above.
+.\"
+There are in addition the following errors that are specific to
+\fBpcre_dfa_exec()\fP:
+.sp
+ PCRE_ERROR_DFA_UITEM (-16)
+.sp
+This return is given if \fBpcre_dfa_exec()\fP encounters an item in the pattern
+that it does not support, for instance, the use of \eC or a back reference.
+.sp
+ PCRE_ERROR_DFA_UCOND (-17)
+.sp
+This return is given if \fBpcre_dfa_exec()\fP encounters a condition item that
+uses a back reference for the condition, or a test for recursion in a specific
+group. These are not supported.
+.sp
+ PCRE_ERROR_DFA_UMLIMIT (-18)
+.sp
+This return is given if \fBpcre_dfa_exec()\fP is called with an \fIextra\fP
+block that contains a setting of the \fImatch_limit\fP field. This is not
+supported (it is meaningless).
+.sp
+ PCRE_ERROR_DFA_WSSIZE (-19)
+.sp
+This return is given if \fBpcre_dfa_exec()\fP runs out of space in the
+\fIworkspace\fP vector.
+.sp
+ PCRE_ERROR_DFA_RECURSE (-20)
+.sp
+When a recursive subpattern is processed, the matching function calls itself
+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
+extremely rare, as a vector of size 1000 is used.
+.
+.
+.SH "SEE ALSO"
+.rs
+.sp
+\fBpcrebuild\fP(3), \fBpcrecallout\fP(3), \fBpcrecpp(3)\fP(3),
+\fBpcrematching\fP(3), \fBpcrepartial\fP(3), \fBpcreposix\fP(3),
+\fBpcreprecompile\fP(3), \fBpcresample\fP(3), \fBpcrestack\fP(3).
+.
+.
+.SH AUTHOR
+.rs
+.sp
+.nf
+Philip Hazel
+University Computing Service
+Cambridge CB2 3QH, England.
+.fi
+.
+.
+.SH REVISION
+.rs
+.sp
+.nf
+Last updated: 11 September 2007
+Copyright (c) 1997-2007 University of Cambridge.
+.fi
Modified: httpd/httpd/vendor/pcre/current/doc/pcrebuild.3
URL: http://svn.apache.org/viewvc/httpd/httpd/vendor/pcre/current/doc/pcrebuild.3?rev=598339&r1=598338&r2=598339&view=diff
==============================================================================
--- httpd/httpd/vendor/pcre/current/doc/pcrebuild.3 (original)
+++ httpd/httpd/vendor/pcre/current/doc/pcrebuild.3 Mon Nov 26 08:49:53 2007
@@ -1,24 +1,40 @@
-.TH PCRE 3
+.TH PCREBUILD 3
.SH NAME
PCRE - Perl-compatible regular expressions
.SH "PCRE BUILD-TIME OPTIONS"
.rs
.sp
This document describes the optional features of PCRE that can be selected when
-the library is compiled. They are all selected, or deselected, by providing
-options to the \fBconfigure\fP script that is run before the \fBmake\fP
-command. The complete list of options for \fBconfigure\fP (which includes the
-standard ones such as the selection of the installation directory) can be
-obtained by running
+the library is compiled. It assumes use of the \fBconfigure\fP script, where
+the optional features are selected or deselected by providing options to
+\fBconfigure\fP before running the \fBmake\fP command. However, the same
+options can be selected in both Unix-like and non-Unix-like environments using
+the GUI facility of \fBCMakeSetup\fP if you are using \fBCMake\fP instead of
+\fBconfigure\fP to build PCRE.
+.P
+The complete list of options for \fBconfigure\fP (which includes the standard
+ones such as the selection of the installation directory) can be obtained by
+running
.sp
./configure --help
.sp
-The following sections describe certain options whose names begin with --enable
-or --disable. These settings specify changes to the defaults for the
+The following sections include descriptions of options whose names begin with
+--enable or --disable. These settings specify changes to the defaults for the
\fBconfigure\fP command. Because of the way that \fBconfigure\fP works,
--enable and --disable always come in pairs, so the complementary option always
exists as well, but as it specifies the default, it is not described.
.
+.SH "C++ SUPPORT"
+.rs
+.sp
+By default, the \fBconfigure\fP script will search for a C++ compiler and C++
+header files. If it finds them, it automatically builds the C++ wrapper library
+for PCRE. You can disable this by adding
+.sp
+ --disable-cpp
+.sp
+to the \fBconfigure\fP command.
+.
.SH "UTF-8 SUPPORT"
.rs
.sp
@@ -45,9 +61,9 @@
to the \fBconfigure\fP command. This implies UTF-8 support, even if you have
not explicitly requested it.
.P
-Including Unicode property support adds around 90K of tables to the PCRE
-library, approximately doubling its size. Only the general category properties
-such as \fILu\fP and \fINd\fP are supported. Details are given in the
+Including Unicode property support adds around 30K of tables to the PCRE
+library. Only the general category properties such as \fILu\fP and \fINd\fP are
+supported. Details are given in the
.\" HREF
\fBpcrepattern\fP
.\"
@@ -56,15 +72,46 @@
.SH "CODE VALUE OF NEWLINE"
.rs
.sp
-By default, PCRE treats character 10 (linefeed) as the newline character. This
-is the normal newline character on Unix-like systems. You can compile PCRE to
-use character 13 (carriage return) instead by adding
+By default, PCRE interprets character 10 (linefeed, LF) as indicating the end
+of a line. This is the normal newline character on Unix-like systems. You can
+compile PCRE to use character 13 (carriage return, CR) instead, by adding
.sp
--enable-newline-is-cr
.sp
-to the \fBconfigure\fP command. For completeness there is also a
---enable-newline-is-lf option, which explicitly specifies linefeed as the
-newline character.
+to the \fBconfigure\fP command. There is also a --enable-newline-is-lf option,
+which explicitly specifies linefeed as the newline character.
+.sp
+Alternatively, you can specify that line endings are to be indicated by the two
+character sequence CRLF. If you want this, add
+.sp
+ --enable-newline-is-crlf
+.sp
+to the \fBconfigure\fP command. There is a fourth option, specified by
+.sp
+ --enable-newline-is-anycrlf
+.sp
+which causes PCRE to recognize any of the three sequences CR, LF, or CRLF as
+indicating a line ending. Finally, a fifth option, specified by
+.sp
+ --enable-newline-is-any
+.sp
+causes PCRE to recognize any Unicode newline sequence.
+.P
+Whatever line ending convention is selected when PCRE is built can be
+overridden when the library functions are called. At build time it is
+conventional to use the standard for your operating system.
+.
+.SH "WHAT \eR MATCHES"
+.rs
+.sp
+By default, the sequence \eR in a pattern matches any Unicode newline sequence,
+whatever has been selected as the line ending sequence. If you specify
+.sp
+ --enable-bsr-anycrlf
+.sp
+the default is changed so that \eR matches only CR, LF, or CRLF. Whatever is
+selected when PCRE is built can be overridden when the library functions are
+called.
.
.SH "BUILDING SHARED AND STATIC LIBRARIES"
.rs
@@ -96,24 +143,6 @@
.sp
to the \fBconfigure\fP command.
.
-.SH "LIMITING PCRE RESOURCE USAGE"
-.rs
-.sp
-Internally, PCRE has a function called \fBmatch()\fP, which it calls repeatedly
-(possibly recursively) when matching a pattern. By controlling the maximum
-number of times this function may be called during a single matching operation,
-a limit can be placed on the resources used by a single call to
-\fBpcre_exec()\fP. The limit can be changed at run time, as described in the
-.\" HREF
-\fBpcreapi\fP
-.\"
-documentation. The default is 10 million, but this can be changed by adding a
-setting such as
-.sp
- --with-match-limit=500000
-.sp
-to the \fBconfigure\fP command.
-.
.SH "HANDLING VERY LARGE PATTERNS"
.rs
.sp
@@ -130,45 +159,124 @@
to the \fBconfigure\fP command. The value given must be 2, 3, or 4. Using
longer offsets slows down the operation of PCRE because it has to load
additional bytes when handling them.
-.P
-If you build PCRE with an increased link size, test 2 (and test 5 if you are
-using UTF-8) will fail. Part of the output of these tests is a representation
-of the compiled pattern, and this changes with the link size.
.
.SH "AVOIDING EXCESSIVE STACK USAGE"
.rs
.sp
-PCRE implements backtracking while matching by making recursive calls to an
-internal function called \fBmatch()\fP. In environments where the size of the
-stack is limited, this can severely limit PCRE's operation. (The Unix
-environment does not usually suffer from this problem.) An alternative approach
-that uses memory from the heap to remember data, instead of using recursive
-function calls, has been implemented to work round this problem. If you want to
+When matching with the \fBpcre_exec()\fP function, PCRE implements backtracking
+by making recursive calls to an internal function called \fBmatch()\fP. In
+environments where the size of the stack is limited, this can severely limit
+PCRE's operation. (The Unix environment does not usually suffer from this
+problem, but it may sometimes be necessary to increase the maximum stack size.
+There is a discussion in the
+.\" HREF
+\fBpcrestack\fP
+.\"
+documentation.) An alternative approach to recursion that uses memory from the
+heap to remember data, instead of using recursive function calls, has been
+implemented to work round the problem of limited stack size. If you want to
build a version of PCRE that works this way, add
.sp
--disable-stack-for-recursion
.sp
to the \fBconfigure\fP command. With this configuration, PCRE will use the
\fBpcre_stack_malloc\fP and \fBpcre_stack_free\fP variables to call memory
-management functions. Separate functions are provided because the usage is very
-predictable: the block sizes requested are always the same, and the blocks are
-always freed in reverse order. A calling program might be able to implement
-optimized functions that perform better than the standard \fBmalloc()\fP and
-\fBfree()\fP functions. PCRE runs noticeably more slowly when built in this
-way.
+management functions. By default these point to \fBmalloc()\fP and
+\fBfree()\fP, but you can replace the pointers so that your own functions are
+used.
+.P
+Separate functions are provided rather than using \fBpcre_malloc\fP and
+\fBpcre_free\fP because the usage is very predictable: the block sizes
+requested are always the same, and the blocks are always freed in reverse
+order. A calling program might be able to implement optimized functions that
+perform better than \fBmalloc()\fP and \fBfree()\fP. PCRE runs noticeably more
+slowly when built in this way. This option affects only the \fBpcre_exec()\fP
+function; it is not relevant for the the \fBpcre_dfa_exec()\fP function.
+.
+.SH "LIMITING PCRE RESOURCE USAGE"
+.rs
+.sp
+Internally, PCRE has a function called \fBmatch()\fP, which it calls repeatedly
+(sometimes recursively) when matching a pattern with the \fBpcre_exec()\fP
+function. By controlling the maximum number of times this function may be
+called during a single matching operation, a limit can be placed on the
+resources used by a single call to \fBpcre_exec()\fP. The limit can be changed
+at run time, as described in the
+.\" HREF
+\fBpcreapi\fP
+.\"
+documentation. The default is 10 million, but this can be changed by adding a
+setting such as
+.sp
+ --with-match-limit=500000
+.sp
+to the \fBconfigure\fP command. This setting has no effect on the
+\fBpcre_dfa_exec()\fP matching function.
+.P
+In some environments it is desirable to limit the depth of recursive calls of
+\fBmatch()\fP more strictly than the total number of calls, in order to
+restrict the maximum amount of stack (or heap, if --disable-stack-for-recursion
+is specified) that is used. A second limit controls this; it defaults to the
+value that is set for --with-match-limit, which imposes no additional
+constraints. However, you can set a lower limit by adding, for example,
+.sp
+ --with-match-limit-recursion=10000
+.sp
+to the \fBconfigure\fP command. This value can also be overridden at run time.
+.
+.SH "CREATING CHARACTER TABLES AT BUILD TIME"
+.rs
+.sp
+PCRE uses fixed tables for processing characters whose code values are less
+than 256. By default, PCRE is built with a set of tables that are distributed
+in the file \fIpcre_chartables.c.dist\fP. These tables are for ASCII codes
+only. If you add
+.sp
+ --enable-rebuild-chartables
+.sp
+to the \fBconfigure\fP command, the distributed tables are no longer used.
+Instead, a program called \fBdftables\fP is compiled and run. This outputs the
+source for new set of tables, created in the default locale of your C runtime
+system. (This method of replacing the tables does not work if you are cross
+compiling, because \fBdftables\fP is run on the local host. If you need to
+create alternative tables when cross compiling, you will have to do so "by
+hand".)
.
.SH "USING EBCDIC CODE"
.rs
.sp
PCRE assumes by default that it will run in an environment where the character
-code is ASCII (or Unicode, which is a superset of ASCII). PCRE can, however, be
-compiled to run in an EBCDIC environment by adding
+code is ASCII (or Unicode, which is a superset of ASCII). This is the case for
+most computer operating systems. PCRE can, however, be compiled to run in an
+EBCDIC environment by adding
.sp
--enable-ebcdic
.sp
-to the \fBconfigure\fP command.
-.P
-.in 0
-Last updated: 09 September 2004
-.br
-Copyright (c) 1997-2004 University of Cambridge.
+to the \fBconfigure\fP command. This setting implies
+--enable-rebuild-chartables. You should only use it if you know that you are in
+an EBCDIC environment (for example, an IBM mainframe operating system).
+.
+.
+.SH "SEE ALSO"
+.rs
+.sp
+\fBpcreapi\fP(3), \fBpcre_config\fP(3).
+.
+.
+.SH AUTHOR
+.rs
+.sp
+.nf
+Philip Hazel
+University Computing Service
+Cambridge CB2 3QH, England.
+.fi
+.
+.
+.SH REVISION
+.rs
+.sp
+.nf
+Last updated: 21 September 2007
+Copyright (c) 1997-2007 University of Cambridge.
+.fi
Modified: httpd/httpd/vendor/pcre/current/doc/pcrecallout.3
URL: http://svn.apache.org/viewvc/httpd/httpd/vendor/pcre/current/doc/pcrecallout.3?rev=598339&r1=598338&r2=598339&view=diff
==============================================================================
--- httpd/httpd/vendor/pcre/current/doc/pcrecallout.3 (original)
+++ httpd/httpd/vendor/pcre/current/doc/pcrecallout.3 Mon Nov 26 08:49:53 2007
@@ -1,4 +1,4 @@
-.TH PCRE 3
+.TH PCRECALLOUT 3
.SH NAME
PCRE - Perl-compatible regular expressions
.SH "PCRE CALLOUTS"
@@ -17,7 +17,7 @@
a number less than 256 after the letter C. The default value is zero.
For example, this pattern has two callout points:
.sp
- (?C1)\deabc(?C2)def
+ (?C1)abc(?C2)def
.sp
If the PCRE_AUTO_CALLOUT option bit is set when \fBpcre_compile()\fP is called,
PCRE automatically inserts callouts, all with number 255, before each item in
@@ -58,9 +58,10 @@
.rs
.sp
During matching, when PCRE reaches a callout point, the external function
-defined by \fIpcre_callout\fP is called (if it is set). The only argument is a
-pointer to a \fBpcre_callout\fP block. This structure contains the following
-fields:
+defined by \fIpcre_callout\fP is called (if it is set). This applies to both
+the \fBpcre_exec()\fP and the \fBpcre_dfa_exec()\fP matching functions. The
+only argument to the callout function is a pointer to a \fBpcre_callout\fP
+block. This structure contains the following fields:
.sp
int \fIversion\fP;
int \fIcallout_number\fP;
@@ -85,34 +86,41 @@
automatically generated callouts).
.P
The \fIoffset_vector\fP field is a pointer to the vector of offsets that was
-passed by the caller to \fBpcre_exec()\fP. The contents can be inspected in
-order to extract substrings that have been matched so far, in the same way as
-for extracting substrings after a match has completed.
+passed by the caller to \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP. When
+\fBpcre_exec()\fP is used, the contents can be inspected in order to extract
+substrings that have been matched so far, in the same way as for extracting
+substrings after a match has completed. For \fBpcre_dfa_exec()\fP this field is
+not useful.
.P
The \fIsubject\fP and \fIsubject_length\fP fields contain copies of the values
that were passed to \fBpcre_exec()\fP.
.P
-The \fIstart_match\fP field contains the offset within the subject at which the
-current match attempt started. If the pattern is not anchored, the callout
-function may be called several times from the same point in the pattern for
-different starting points in the subject.
+The \fIstart_match\fP field normally contains the offset within the subject at
+which the current match attempt started. However, if the escape sequence \eK
+has been encountered, this value is changed to reflect the modified starting
+point. If the pattern is not anchored, the callout function may be called
+several times from the same point in the pattern for different starting points
+in the subject.
.P
The \fIcurrent_position\fP field contains the offset within the subject of the
current match pointer.
.P
-The \fIcapture_top\fP field contains one more than the number of the highest
-numbered captured substring so far. If no substrings have been captured,
-the value of \fIcapture_top\fP is one.
+When the \fBpcre_exec()\fP function is used, the \fIcapture_top\fP field
+contains one more than the number of the highest numbered captured substring so
+far. If no substrings have been captured, the value of \fIcapture_top\fP is
+one. This is always the case when \fBpcre_dfa_exec()\fP is used, because it
+does not support captured substrings.
.P
The \fIcapture_last\fP field contains the number of the most recently captured
-substring. If no substrings have been captured, its value is -1.
+substring. If no substrings have been captured, its value is -1. This is always
+the case when \fBpcre_dfa_exec()\fP is used.
.P
The \fIcallout_data\fP field contains a value that is passed to
-\fBpcre_exec()\fP by the caller specifically so that it can be passed back in
-callouts. It is passed in the \fIpcre_callout\fP field of the \fBpcre_extra\fP
-data structure. If no such data was passed, the value of \fIcallout_data\fP in
-a \fBpcre_callout\fP block is NULL. There is a description of the
-\fBpcre_extra\fP structure in the
+\fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP specifically so that it can be
+passed back in callouts. It is passed in the \fIpcre_callout\fP field of the
+\fBpcre_extra\fP data structure. If no such data was passed, the value of
+\fIcallout_data\fP in a \fBpcre_callout\fP block is NULL. There is a
+description of the \fBpcre_extra\fP structure in the
.\" HREF
\fBpcreapi\fP
.\"
@@ -139,17 +147,31 @@
.sp
The external callout function returns an integer to PCRE. If the value is zero,
matching proceeds as normal. If the value is greater than zero, matching fails
-at the current point, but backtracking to test other matching possibilities
-goes ahead, just as if a lookahead assertion had failed. If the value is less
-than zero, the match is abandoned, and \fBpcre_exec()\fP returns the negative
-value.
+at the current point, but the testing of other matching possibilities goes
+ahead, just as if a lookahead assertion had failed. If the value is less than
+zero, the match is abandoned, and \fBpcre_exec()\fP (or \fBpcre_dfa_exec()\fP)
+returns the negative value.
.P
Negative values should normally be chosen from the set of PCRE_ERROR_xxx
values. In particular, PCRE_ERROR_NOMATCH forces a standard "no match" failure.
The error number PCRE_ERROR_CALLOUT is reserved for use by callout functions;
it will never be used by PCRE itself.
-.P
-.in 0
-Last updated: 09 September 2004
-.br
-Copyright (c) 1997-2004 University of Cambridge.
+.
+.
+.SH AUTHOR
+.rs
+.sp
+.nf
+Philip Hazel
+University Computing Service
+Cambridge CB2 3QH, England.
+.fi
+.
+.
+.SH REVISION
+.rs
+.sp
+.nf
+Last updated: 29 May 2007
+Copyright (c) 1997-2007 University of Cambridge.
+.fi