doc/pcre_dfa_exec.3

   1 .TH PCRE_DFA_EXEC 3 "12 May 2013" "PCRE 8.33"
   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_dfa_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 "     int *\fIworkspace\fP, int \fIwscount\fP);"
  14 .sp
  15 .B int pcre16_dfa_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 "     int *\fIworkspace\fP, int \fIwscount\fP);"
  19 .sp
  20 .B int pcre32_dfa_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 "     int *\fIworkspace\fP, int \fIwscount\fP);"
  24 .fi
  25 .
  26 .SH DESCRIPTION
  27 .rs
  28 .sp
  29 This function matches a compiled regular expression against a given subject
  30 string, using an alternative matching algorithm that scans the subject string
  31 just once (\fInot\fP Perl-compatible). Note that the main, Perl-compatible,
  32 matching function is \fBpcre[16|32]_exec()\fP. The arguments for this function
  33 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
  40   \fIstartoffset\fP  Offset in the subject at which to start matching
  41   \fIoptions\fP      Option bits
  42   \fIovector\fP      Points to a vector of ints for result offsets
  43   \fIovecsize\fP     Number of elements in the vector
  44   \fIworkspace\fP    Points to a vector of ints used as working space
  45   \fIwscount\fP      Number of elements in the vector
  46 .sp
  47 The units for \fIlength\fP and \fIstartoffset\fP are bytes for
  48 \fBpcre_exec()\fP, 16-bit data items for \fBpcre16_exec()\fP, and 32-bit items
  49 for \fBpcre32_exec()\fP. The options are:
  50 .sp
  51   PCRE_ANCHORED          Match only at the first position
  52   PCRE_BSR_ANYCRLF       \eR matches only CR, LF, or CRLF
  53   PCRE_BSR_UNICODE       \eR matches all Unicode line endings
  54   PCRE_NEWLINE_ANY       Recognize any Unicode newline sequence
  55   PCRE_NEWLINE_ANYCRLF   Recognize CR, LF, & CRLF as newline sequences
  56   PCRE_NEWLINE_CR        Recognize CR as the only newline sequence
  57   PCRE_NEWLINE_CRLF      Recognize CRLF as the only newline sequence
  58   PCRE_NEWLINE_LF        Recognize LF as the only newline sequence
  59   PCRE_NOTBOL            Subject is not the beginning of a line
  60   PCRE_NOTEOL            Subject is not the end of a line
  61   PCRE_NOTEMPTY          An empty string is not a valid match
  62   PCRE_NOTEMPTY_ATSTART  An empty string at the start of the subject
  63                            is not a valid match
  64   PCRE_NO_START_OPTIMIZE Do not do "start-match" optimizations
  65   PCRE_NO_UTF16_CHECK    Do not check the subject for UTF-16
  66                            validity (only relevant if PCRE_UTF16
  67                            was set at compile time)
  68   PCRE_NO_UTF32_CHECK    Do not check the subject for UTF-32
  69                            validity (only relevant if PCRE_UTF32
  70                            was set at compile time)
  71   PCRE_NO_UTF8_CHECK     Do not check the subject for UTF-8
  72                            validity (only relevant if PCRE_UTF8
  73                            was set at compile time)
  74   PCRE_PARTIAL           ) Return PCRE_ERROR_PARTIAL for a partial
  75   PCRE_PARTIAL_SOFT      )   match if no full matches are found
  76   PCRE_PARTIAL_HARD      Return PCRE_ERROR_PARTIAL for a partial match
  77                            even if there is a full match as well
  78   PCRE_DFA_SHORTEST      Return only the shortest match
  79   PCRE_DFA_RESTART       Restart after a partial match
  80 .sp
  81 There are restrictions on what may appear in a pattern when using this matching
  82 function. Details are given in the
  83 .\" HREF
  84 \fBpcrematching\fP
  85 .\"
  86 documentation. For details of partial matching, see the
  87 .\" HREF
  88 \fBpcrepartial\fP
  89 .\"
  90 page.
  91 .P
  92 A \fBpcre[16|32]_extra\fP structure contains the following fields:
  93 .sp
  94   \fIflags\fP            Bits indicating which fields are set
  95   \fIstudy_data\fP       Opaque data from \fBpcre[16|32]_study()\fP
  96   \fImatch_limit\fP      Limit on internal resource use
  97   \fImatch_limit_recursion\fP  Limit on internal recursion depth
  98   \fIcallout_data\fP     Opaque data passed back to callouts
  99   \fItables\fP           Points to character tables or is NULL
 100   \fImark\fP             For passing back a *MARK pointer
 101   \fIexecutable_jit\fP   Opaque data from JIT compilation
 102 .sp
 103 The flag bits are PCRE_EXTRA_STUDY_DATA, PCRE_EXTRA_MATCH_LIMIT,
 104 PCRE_EXTRA_MATCH_LIMIT_RECURSION, PCRE_EXTRA_CALLOUT_DATA,
 105 PCRE_EXTRA_TABLES, PCRE_EXTRA_MARK and PCRE_EXTRA_EXECUTABLE_JIT. For this
 106 matching function, the \fImatch_limit\fP and \fImatch_limit_recursion\fP fields
 107 are not used, and must not be set. The PCRE_EXTRA_EXECUTABLE_JIT flag and
 108 the corresponding variable are ignored.
 109 .P
 110 There is a complete description of the PCRE native API in the
 111 .\" HREF
 112 \fBpcreapi\fP
 113 .\"
 114 page and a description of the POSIX API in the
 115 .\" HREF
 116 \fBpcreposix\fP
 117 .\"
 118 page.