Revision: 686
http://vcs.pcre.org/viewvc?view=rev&revision=686
Author: ph10
Date: 2011-09-06 17:06:36 +0100 (Tue, 06 Sep 2011)
Log Message:
-----------
More documentation updates.
Modified Paths:
--------------
code/trunk/doc/pcreapi.3
code/trunk/doc/pcrejit.3
Modified: code/trunk/doc/pcreapi.3
===================================================================
--- code/trunk/doc/pcreapi.3 2011-09-06 15:02:07 UTC (rev 685)
+++ code/trunk/doc/pcreapi.3 2011-09-06 16:06:36 UTC (rev 686)
@@ -111,7 +111,11 @@
.B int pcre_config(int \fIwhat\fP, void *\fIwhere\fP);
.PP
.B char *pcre_version(void);
-.PP
+.
+.
+.SH "PCRE NATIVE API INDIRECTED FUNCTIONS"
+.rs
+.sp
.B void *(*pcre_malloc)(size_t);
.PP
.B void (*pcre_free)(void *);
@@ -168,11 +172,12 @@
documentation describes how to compile and run it.
.P
Just-in-time compiler support is an optional feature of PCRE that can be built
-in appropriate hardware environments. It greatly speeds up the matching
-performance of many patterns. Simple programs can request its use if available.
-More complicated programs might need to make use of the
-\fBpcre_jit_stack_alloc()\fP, \fBpcre_jit_stack_free()\fP, and
-\fBpcre_assign_jit_stack()\fP functions in order to control its memory usage.
+in appropriate hardware environments. It greatly speeds up the matching
+performance of many patterns. Simple programs can easily request that it be
+used if available, by setting an option that is ignored when it is not
+relevant. More complicated programs might need to make use of the functions
+\fBpcre_jit_stack_alloc()\fP, \fBpcre_jit_stack_free()\fP, and
+\fBpcre_assign_jit_stack()\fP in order to control the JIT code's memory usage.
These functions are discussed in the
.\" HREF
\fBpcrejit\fP
@@ -1430,8 +1435,8 @@
.P
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
-stack, the amount of heap memory that can be used. This limit is relevant, and
-is ignored, when the pattern was successfully studied with
+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
PCRE_STUDY_JIT_COMPILE.
.P
The default value for \fImatch_limit_recursion\fP can be set when PCRE is
@@ -1491,6 +1496,13 @@
PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART,
PCRE_NO_START_OPTIMIZE, PCRE_NO_UTF8_CHECK, PCRE_PARTIAL_SOFT, and
PCRE_PARTIAL_HARD.
+.P
+If the pattern was successfully studied with the PCRE_STUDY_JIT_COMPILE option,
+the only supported options for JIT execution are PCRE_NO_UTF8_CHECK,
+PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, and PCRE_NOTEMPTY_ATSTART. Note in
+particular that partial matching is not supported. If an unsupported option is
+used, JIT execution is disabled and the normal interpretive code in
+\fBpcre_exec()\fP is run.
.sp
PCRE_ANCHORED
.sp
@@ -1797,13 +1809,28 @@
.P
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
-returns a value of zero. If the substring offsets are not of interest,
-\fBpcre_exec()\fP may be called with \fIovector\fP 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 substrings, PCRE
-has to get additional memory for use during matching. Thus it is usually
-advisable to supply an \fIovector\fP.
+returns a value of zero. If neither the actual string matched not any captured
+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
+back references and the \fIovector\fP is not big enough to remember the related
+substrings, PCRE has to get additional memory for use during matching. Thus it
+is usually advisable to supply an \fIovector\fP of reasonable size.
.P
+There are some cases where zero is returned (indicating vector overflow) when
+in fact the vector is exactly the right size for the final match. For example,
+consider the pattern
+.sp
+ (a)(?:(b)c|bd)
+.sp
+If a vector of 6 elements (allowing for only 1 captured substring) is given
+with subject string "abd", \fBpcre_exec()\fP will try to set the second
+captured string, thereby recording a vector overflow, before failing to match
+"c" and backing up to try the second alternative. The zero return, however,
+does correctly indicate that the maximum number of slots (namely 2) have been
+filled. In similar cases where there is temporary overflow, but the final
+number of used slots is actually less than the maximum, a non-zero value is
+returned.
+.P
The \fBpcre_fullinfo()\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
@@ -1823,7 +1850,7 @@
number is 1, and the offsets for for the second and third capturing subpatterns
(assuming the vector is large enough, of course) are set to -1.
.P
-\fBNote\fP: Elements in the first two-thids of \fIovector\fP that do not
+\fBNote\fP: Elements in the first two-thirds of \fIovector\fP that do not
correspond to capturing parentheses in the pattern are never changed. That is,
if a pattern contains \fIn\fP capturing parentheses, no more than
\fIovector[0]\fP to \fIovector[2n+1]\fP are set by \fBpcre_exec()\fP. The other
@@ -1983,8 +2010,8 @@
PCRE_ERROR_JIT_STACKLIMIT (-27)
.sp
This error is returned when a pattern that was successfully studied using the
-PCRE_STUDY_JIT_COMPILE option is matched, but the memory available for the
-just-in-time processing stack is not large enough. See the
+PCRE_STUDY_JIT_COMPILE option is being matched, but the memory available for
+the just-in-time processing stack is not large enough. See the
.\" HREF
\fBpcrejit\fP
.\"
@@ -2229,6 +2256,7 @@
numbers. For this reason, the use of different names for subpatterns of the
same number causes an error at compile time.
.
+.
.SH "DUPLICATE SUBPATTERN NAMES"
.rs
.sp
@@ -2498,6 +2526,6 @@
.rs
.sp
.nf
-Last updated: 29 August 2011
+Last updated: 06 September 2011
Copyright (c) 1997-2011 University of Cambridge.
.fi
Modified: code/trunk/doc/pcrejit.3
===================================================================
--- code/trunk/doc/pcrejit.3 2011-09-06 15:02:07 UTC (rev 685)
+++ code/trunk/doc/pcrejit.3 2011-09-06 16:06:36 UTC (rev 686)
@@ -149,11 +149,11 @@
managing blocks of memory for use as JIT stacks.
.P
The \fBpcre_jit_stack_alloc()\fP function creates a JIT stack. Its arguments
-are a starting size and a maximum size, and it returns an opaque value
-of type \fBpcre_jit_stack\fP that represents a JIT stack, or NULL if there is
-an error. The \fBpcre_jit_stack_free()\fP function can be used to free a stack
-that is no longer needed. (For the technically minded: the address space is
-allocated by mmap or VirtualAlloc.)
+are a starting size and a maximum size, and it returns a pointer to an opaque
+structure of type \fBpcre_jit_stack\fP, or NULL if there is an error. The
+\fBpcre_jit_stack_free()\fP function can be used to free a stack that is no
+longer needed. (For the technically minded: the address space is allocated by
+mmap or VirtualAlloc.)
.P
JIT uses far less memory for recursion than the interpretive code,
and a maximum stack size of 512K to 1M should be more than enough for any
