--- code/trunk/doc/html/pcrecallout.html 2007/06/05 10:40:13 172 +++ code/trunk/doc/html/pcrecallout.html 2011/12/05 12:33:44 784 @@ -39,9 +39,10 @@
   (?C1)abc(?C2)def
 
-If the PCRE_AUTO_CALLOUT option bit is set when pcre_compile() is called, -PCRE automatically inserts callouts, all with number 255, before each item in -the pattern. For example, if PCRE_AUTO_CALLOUT is used with the pattern +If the PCRE_AUTO_CALLOUT option bit is set when pcre_compile() or +pcre_compile2() is called, PCRE automatically inserts callouts, all with +number 255, before each item in the pattern. For example, if PCRE_AUTO_CALLOUT +is used with the pattern
   A(\d{2}|--)
 
@@ -59,10 +60,16 @@ indicates how the pattern is matched. This is useful information when you are trying to optimize the performance of a particular pattern.

+

+The use of callouts in a pattern makes it ineligible for optimization by the +just-in-time compiler. Studying such a pattern with the PCRE_STUDY_JIT_COMPILE +option always fails. +


MISSING CALLOUTS

You should be aware that, because of optimizations in the way PCRE matches -patterns, callouts sometimes do not happen. For example, if the pattern is +patterns by default, callouts sometimes do not happen. For example, if the +pattern is

   ab(?C4)cd
 
@@ -71,6 +78,18 @@ the callout is never reached. However, with "abyd", though the result is still no match, the callout is obeyed.

+

+If the pattern is studied, PCRE knows the minimum length of a matching string, +and will immediately give a "no match" return without actually running a match +if the subject is not long enough, or, for unanchored patterns, if it has +been scanned far enough. +

+

+You can disable these optimizations by passing the PCRE_NO_START_OPTIMIZE +option to pcre_compile(), pcre_exec(), or pcre_dfa_exec(), +or by starting the pattern with (*NO_START_OPT). This slows down the matching +process, but does ensure that callouts such as the example above are obeyed. +


THE CALLOUT INTERFACE

During matching, when PCRE reaches a callout point, the external function @@ -79,21 +98,22 @@ only argument to the callout function is a pointer to a pcre_callout block. This structure contains the following fields:

-  int          version;
-  int          callout_number;
-  int         *offset_vector;
-  const char  *subject;
-  int          subject_length;
-  int          start_match;
-  int          current_position;
-  int          capture_top;
-  int          capture_last;
-  void        *callout_data;
-  int          pattern_position;
-  int          next_item_length;
+  int         version;
+  int         callout_number;
+  int        *offset_vector;
+  const char *subject;
+  int         subject_length;
+  int         start_match;
+  int         current_position;
+  int         capture_top;
+  int         capture_last;
+  void       *callout_data;
+  int         pattern_position;
+  int         next_item_length;
+  const unsigned char *mark;
 
The version field is an integer containing the version number of the -block format. The initial version was 0; the current version is 1. The version +block format. The initial version was 0; the current version is 2. The version number will change again in future if additional fields are added, but the intention is never to remove any of the existing fields.

@@ -166,13 +186,21 @@ help in distinguishing between different automatic callouts, which all have the same callout number. However, they are set for all callouts.

+

+The mark field is present from version 2 of the pcre_callout +structure. In callouts from pcre_exec() it contains a pointer to the +zero-terminated name of the most recently passed (*MARK), (*PRUNE), or (*THEN) +item in the match, or NULL if no such items have been passed. Instances of +(*PRUNE) or (*THEN) without a name do not obliterate a previous (*MARK). In +callouts from pcre_dfa_exec() this field always contains NULL. +


RETURN VALUES

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 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 pcre_exec() (or pcre_dfa_exec()) +zero, the match is abandoned, and pcre_exec() or pcre_dfa_exec() returns the negative value.

@@ -192,9 +220,9 @@


REVISION

-Last updated: 29 May 2007 +Last updated: 30 November 2011
-Copyright © 1997-2007 University of Cambridge. +Copyright © 1997-2011 University of Cambridge.

Return to the PCRE index page.