+Return to the PCRE index page. +
+
+This page is part of the PCRE HTML documentation. It was generated automatically
+from the original man page. If there is any nonsense in it, please consult the
+man page, in case the conversion went wrong.
+
@@ -26,18 +34,47 @@ function is to be called. Different callout points can be identified by putting a number less than 256 after the letter C. The default value is zero. For example, this pattern has two callout points: -
-
- (?C1)\dabc(?C2)def -- -
-During matching, when PCRE reaches a callout point (and pcre_callout is -set), the external function is called. Its only argument is a pointer to a -pcre_callout block. This contains the following variables: + (?C1)\deabc(?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 +
+ A(\d{2}|--)
+
+it is processed as if it were
++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 +
+ ab(?C4)cd ++PCRE knows that any matching string must contain the letter "d". If the subject +string is "abyz", the lack of "d" means that matching doesn't ever start, and +the callout is never reached. However, with "abyd", though the result is still +no match, the callout is obeyed. + +
+During matching, when PCRE reaches a callout point, the external function +defined by pcre_callout is called (if it is set). The only argument is a +pointer to a pcre_callout block. This structure contains the following +fields:
int version; int callout_number; @@ -49,17 +86,18 @@ int capture_top; int capture_last; void *callout_data; -- -
+ int pattern_position; + int next_item_length; + The version field is an integer containing the version number of the -block format. The current version is zero. The version number may change in -future if additional fields are added, but the intention is never to remove any -of the existing fields. +block format. The initial version was 0; the current version is 1. 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.
The callout_number field contains the number of the callout, as compiled -into the pattern (that is, the number after ?C). +into the pattern (that is, the number after ?C for manual callouts, and 255 for +automatically generated callouts).
The offset_vector field is a pointer to the vector of offsets that was @@ -68,13 +106,14 @@ for extracting substrings after a match has completed.
-The subject and subject_length fields contain copies the values +The subject and subject_length fields contain copies of the values that were passed to pcre_exec().
The start_match 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 for different starting points. +function may be called several times from the same point in the pattern for +different starting points in the subject.
The current_position field contains the offset within the subject of the @@ -87,7 +126,7 @@
The capture_last field contains the number of the most recently captured -substring. +substring. If no substrings have been captured, its value is -1.
The callout_data field contains a value that is passed to @@ -95,15 +134,36 @@ callouts. It is passed in the pcre_callout field of the pcre_extra data structure. If no such data was passed, the value of callout_data in a pcre_callout block is NULL. There is a description of the -pcre_extra structure in the pcreapi documentation. +pcre_extra structure in the +pcreapi +documentation. +
++The pattern_position field is present from version 1 of the +pcre_callout structure. It contains the offset to the next item to be +matched in the pattern string. +
++The next_item_length field is present from version 1 of the +pcre_callout structure. It contains the length of the next item to be +matched in the pattern string. When the callout immediately precedes an +alternation bar, a closing parenthesis, or the end of the pattern, the length +is zero. When the callout precedes an opening parenthesis, the length is that +of the entire subpattern. +
++The pattern_position and next_item_length fields are intended to +help in distinguishing between different automatic callouts, which all have the +same callout number. However, they are set for all callouts.
--The callout function returns an integer. 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 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() returns the value. +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 pcre_exec() returns the negative +value.
Negative values should normally be chosen from the set of PCRE_ERROR_xxx @@ -112,6 +172,9 @@ it will never be used by PCRE itself.
-Last updated: 21 January 2003
+Last updated: 09 September 2004
-Copyright © 1997-2003 University of Cambridge.
+Copyright © 1997-2004 University of Cambridge.
+
+Return to the PCRE index page. +