PCRE(3)                                                   PCRE(3)



NAME
       PCRE - Perl-compatible regular expressions

PCRE CALLOUTS

       int (*pcre_callout)(pcre_callout_block *);

       PCRE provides a feature called "callout", which is a means
       of temporarily passing control to the caller  of  PCRE  in
       the  middle  of  pattern matching. The caller of PCRE pro-
       vides an external function by putting its entry  point  in
       the  global  variable pcre_callout. By default, this vari-
       able contains NULL, which disables all calling out.

       Within a regular expression, (?C) indicates the points  at
       which  the  external  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)abc(?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:

         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;

       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.

       The  callout_number field contains the number of the call-
       out, as compiled into the pattern  (that  is,  the  number
       after ?C).

       The offset_vector field is a pointer to the vector of off-
       sets that was passed by the  caller  to  pcre_exec().  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.

       The  subject  and subject_length fields contain copies the
       values that were passed to pcre_exec().

       The start_match field contains the offset within the  sub-
       ject  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.

       The  current_position field contains the offset within the
       subject of the current match pointer.

       The capture_top field contains one more than the number of
       the highest numbered captured substring so far. If no sub-
       strings have been captured, the value  of  capture_top  is
       one.

       The  capture_last  field  contains  the number of the most
       recently captured substring.

       The callout_data field contains a value that is passed  to
       pcre_exec()  by  the caller specifically so that it can be
       passed back in 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.



RETURN VALUES

       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  back-
       tracking  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.

       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 func-
       tions; it will never be used by PCRE itself.

Last updated: 21 January 2003
Copyright (c) 1997-2003 University of Cambridge.



                                                          PCRE(3)