doc/pcre_jit_exec.3

   1 .TH PCRE_EXEC 3 "31 October 2012" "PCRE 8.30"
   2 .SH NAME
   3 PCRE - Perl-compatible regular expressions
   4 .SH SYNOPSIS
   5 .rs
   6 .sp
   7 .B #include <pcre.h>
   8 .PP
   9 .nf
  10 .B int pcre_jit_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP,"
  11 .B "     const char *\fIsubject\fP, int \fIlength\fP, int \fIstartoffset\fP,"
  12 .B "     int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP,"
  13 .B "     pcre_jit_stack *\fIjstack\fP);"
  14 .sp
  15 .B int pcre16_jit_exec(const pcre16 *\fIcode\fP, "const pcre16_extra *\fIextra\fP,"
  16 .B "     PCRE_SPTR16 \fIsubject\fP, int \fIlength\fP, int \fIstartoffset\fP,"
  17 .B "     int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP,"
  18 .B "     pcre_jit_stack *\fIjstack\fP);"
  19 .sp
  20 .B int pcre32_jit_exec(const pcre32 *\fIcode\fP, "const pcre32_extra *\fIextra\fP,"
  21 .B "     PCRE_SPTR32 \fIsubject\fP, int \fIlength\fP, int \fIstartoffset\fP,"
  22 .B "     int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP,"
  23 .B "     pcre_jit_stack *\fIjstack\fP);"
  24 .fi
  25 .
  26 .SH DESCRIPTION
  27 .rs
  28 .sp
  29 This function matches a compiled regular expression that has been successfully
  30 studied with one of the JIT options against a given subject string, using a
  31 matching algorithm that is similar to Perl's. It is a "fast path" interface to
  32 JIT, and it bypasses some of the sanity checks that \fBpcre_exec()\fP applies.
  33 It returns offsets to captured substrings. Its arguments are:
  34 .sp
  35   \fIcode\fP         Points to the compiled pattern
  36   \fIextra\fP        Points to an associated \fBpcre[16|32]_extra\fP structure,
  37                  or is NULL
  38   \fIsubject\fP      Points to the subject string
  39   \fIlength\fP       Length of the subject string, in bytes
  40   \fIstartoffset\fP  Offset in bytes in the subject at which to
  41                  start matching
  42   \fIoptions\fP      Option bits
  43   \fIovector\fP      Points to a vector of ints for result offsets
  44   \fIovecsize\fP     Number of elements in the vector (a multiple of 3)
  45   \fIjstack\fP       Pointer to a JIT stack
  46 .sp
  47 The allowed options are:
  48 .sp
  49   PCRE_NOTBOL            Subject string is not the beginning of a line
  50   PCRE_NOTEOL            Subject string is not the end of a line
  51   PCRE_NOTEMPTY          An empty string is not a valid match
  52   PCRE_NOTEMPTY_ATSTART  An empty string at the start of the subject
  53                            is not a valid match
  54   PCRE_NO_UTF16_CHECK    Do not check the subject for UTF-16
  55                            validity (only relevant if PCRE_UTF16
  56                            was set at compile time)
  57   PCRE_NO_UTF32_CHECK    Do not check the subject for UTF-32
  58                            validity (only relevant if PCRE_UTF32
  59                            was set at compile time)
  60   PCRE_NO_UTF8_CHECK     Do not check the subject for UTF-8
  61                            validity (only relevant if PCRE_UTF8
  62                            was set at compile time)
  63   PCRE_PARTIAL           ) Return PCRE_ERROR_PARTIAL for a partial
  64   PCRE_PARTIAL_SOFT      )   match if no full matches are found
  65   PCRE_PARTIAL_HARD      Return PCRE_ERROR_PARTIAL for a partial match
  66                            if that is found before a full match
  67 .sp
  68 However, the PCRE_NO_UTF[8|16|32]_CHECK options have no effect, as this check
  69 is never applied. For details of partial matching, see the
  70 .\" HREF
  71 \fBpcrepartial\fP
  72 .\"
  73 page. A \fBpcre_extra\fP structure contains the following fields:
  74 .sp
  75   \fIflags\fP            Bits indicating which fields are set
  76   \fIstudy_data\fP       Opaque data from \fBpcre[16|32]_study()\fP
  77   \fImatch_limit\fP      Limit on internal resource use
  78   \fImatch_limit_recursion\fP  Limit on internal recursion depth
  79   \fIcallout_data\fP     Opaque data passed back to callouts
  80   \fItables\fP           Points to character tables or is NULL
  81   \fImark\fP             For passing back a *MARK pointer
  82   \fIexecutable_jit\fP   Opaque data from JIT compilation
  83 .sp
  84 The flag bits are PCRE_EXTRA_STUDY_DATA, PCRE_EXTRA_MATCH_LIMIT,
  85 PCRE_EXTRA_MATCH_LIMIT_RECURSION, PCRE_EXTRA_CALLOUT_DATA,
  86 PCRE_EXTRA_TABLES, PCRE_EXTRA_MARK and PCRE_EXTRA_EXECUTABLE_JIT.
  87 .P
  88 There is a complete description of the PCRE native API in the
  89 .\" HREF
  90 \fBpcreapi\fP
  91 .\"
  92 page and a description of the JIT API in the
  93 .\" HREF
  94 \fBpcrejit\fP
  95 .\"
  96 page.