/[pcre]/code/trunk/doc/html/pcreapi.html
ViewVC logotype

Diff of /code/trunk/doc/html/pcreapi.html

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 929 by ph10, Sat Jan 21 16:37:17 2012 UTC revision 930 by ph10, Fri Feb 24 12:05:54 2012 UTC
# Line 524  documentation). For those options that c Line 524  documentation). For those options that c
524  the pattern, the contents of the <i>options</i> argument specifies their  the pattern, the contents of the <i>options</i> argument specifies their
525  settings at the start of compilation and execution. The PCRE_ANCHORED,  settings at the start of compilation and execution. The PCRE_ANCHORED,
526  PCRE_BSR_<i>xxx</i>, PCRE_NEWLINE_<i>xxx</i>, PCRE_NO_UTF8_CHECK, and  PCRE_BSR_<i>xxx</i>, PCRE_NEWLINE_<i>xxx</i>, PCRE_NO_UTF8_CHECK, and
527  PCRE_NO_START_OPT options can be set at the time of matching as well as at  PCRE_NO_START_OPTIMIZE options can be set at the time of matching as well as at
528  compile time.  compile time.
529  </P>  </P>
530  <P>  <P>
# Line 949  wants to pass any of the other fields to Line 949  wants to pass any of the other fields to
949  <b>pcre_dfa_exec()</b>, it must set up its own <b>pcre_extra</b> block.  <b>pcre_dfa_exec()</b>, it must set up its own <b>pcre_extra</b> block.
950  </P>  </P>
951  <P>  <P>
952  The second argument of <b>pcre_study()</b> contains option bits. There is only  The second argument of <b>pcre_study()</b> contains option bits. There are three
953  one option: PCRE_STUDY_JIT_COMPILE. If this is set, and the just-in-time  options:
954  compiler is available, the pattern is further compiled into machine code that  <pre>
955  executes much faster than the <b>pcre_exec()</b> matching function. If    PCRE_STUDY_JIT_COMPILE
956  the just-in-time compiler is not available, this option is ignored. All other    PCRE_STUDY_JIT_PARTIAL_HARD_COMPILE
957  bits in the <i>options</i> argument must be zero.    PCRE_STUDY_JIT_PARTIAL_SOFT_COMPILE
958    </pre>
959    If any of these are set, and the just-in-time compiler is available, the
960    pattern is further compiled into machine code that executes much faster than
961    the <b>pcre_exec()</b> interpretive matching function. If the just-in-time
962    compiler is not available, these options are ignored. All other bits in the
963    <i>options</i> argument must be zero.
964  </P>  </P>
965  <P>  <P>
966  JIT compilation is a heavyweight optimization. It can take some time for  JIT compilation is a heavyweight optimization. It can take some time for
# Line 979  When you are finished with a pattern, yo Line 985  When you are finished with a pattern, yo
985  study data by calling <b>pcre_free_study()</b>. This function was added to the  study data by calling <b>pcre_free_study()</b>. This function was added to the
986  API for release 8.20. For earlier versions, the memory could be freed with  API for release 8.20. For earlier versions, the memory could be freed with
987  <b>pcre_free()</b>, just like the pattern itself. This will still work in cases  <b>pcre_free()</b>, just like the pattern itself. This will still work in cases
988  where PCRE_STUDY_JIT_COMPILE is not used, but it is advisable to change to the  where JIT optimization is not used, but it is advisable to change to the new
989  new function when convenient.  function when convenient.
990  </P>  </P>
991  <P>  <P>
992  This is a typical way in which <b>pcre_study</b>() is used (except that in a  This is a typical way in which <b>pcre_study</b>() is used (except that in a
# Line 1016  matching. (In 16-bit mode, the bitmap is Line 1022  matching. (In 16-bit mode, the bitmap is
1022  </P>  </P>
1023  <P>  <P>
1024  These two optimizations apply to both <b>pcre_exec()</b> and  These two optimizations apply to both <b>pcre_exec()</b> and
1025  <b>pcre_dfa_exec()</b>. However, they are not used by <b>pcre_exec()</b> if  <b>pcre_dfa_exec()</b>, and the information is also used by the JIT compiler.
1026  <b>pcre_study()</b> is called with the PCRE_STUDY_JIT_COMPILE option, and  The optimizations can be disabled by setting the PCRE_NO_START_OPTIMIZE option
1027  just-in-time compiling is successful. The optimizations can be disabled by  when calling <b>pcre_exec()</b> or <b>pcre_dfa_exec()</b>, but if this is done,
1028  setting the PCRE_NO_START_OPTIMIZE option when calling <b>pcre_exec()</b> or  JIT execution is also disabled. You might want to do this if your pattern
1029  <b>pcre_dfa_exec()</b>. You might want to do this if your pattern contains  contains callouts or (*MARK) and you want to make use of these facilities in
1030  callouts or (*MARK) (which cannot be handled by the JIT compiler), and you want  cases where matching fails. See the discussion of PCRE_NO_START_OPTIMIZE
 to make use of these facilities in cases where matching fails. See the  
 discussion of PCRE_NO_START_OPTIMIZE  
1031  <a href="#execoptions">below.</a>  <a href="#execoptions">below.</a>
1032  <a name="localesupport"></a></P>  <a name="localesupport"></a></P>
1033  <br><a name="SEC14" href="#TOC1">LOCALE SUPPORT</a><br>  <br><a name="SEC14" href="#TOC1">LOCALE SUPPORT</a><br>
# Line 1199  Return 1 if the (?J) or (?-J) option set Line 1203  Return 1 if the (?J) or (?-J) option set
1203  <pre>  <pre>
1204    PCRE_INFO_JIT    PCRE_INFO_JIT
1205  </pre>  </pre>
1206  Return 1 if the pattern was studied with the PCRE_STUDY_JIT_COMPILE option, and  Return 1 if the pattern was studied with one of the JIT options, and
1207  just-in-time compiling was successful. The fourth argument should point to an  just-in-time compiling was successful. The fourth argument should point to an
1208  <b>int</b> variable. A return value of 0 means that JIT support is not available  <b>int</b> variable. A return value of 0 means that JIT support is not available
1209  in this version of PCRE, or that the pattern was not studied with the  in this version of PCRE, or that the pattern was not studied with a JIT option,
1210  PCRE_STUDY_JIT_COMPILE option, or that the JIT compiler could not handle this  or that the JIT compiler could not handle this particular pattern. See the
 particular pattern. See the  
1211  <a href="pcrejit.html"><b>pcrejit</b></a>  <a href="pcrejit.html"><b>pcrejit</b></a>
1212  documentation for details of what can and cannot be handled.  documentation for details of what can and cannot be handled.
1213  <pre>  <pre>
1214    PCRE_INFO_JITSIZE    PCRE_INFO_JITSIZE
1215  </pre>  </pre>
1216  If the pattern was successfully studied with the PCRE_STUDY_JIT_COMPILE option,  If the pattern was successfully studied with a JIT option, return the size of
1217  return the size of the JIT compiled code, otherwise return zero. The fourth  the JIT compiled code, otherwise return zero. The fourth argument should point
1218  argument should point to a <b>size_t</b> variable.  to a <b>size_t</b> variable.
1219  <pre>  <pre>
1220    PCRE_INFO_LASTLITERAL    PCRE_INFO_LASTLITERAL
1221  </pre>  </pre>
# Line 1439  In the 16-bit version of this structure, Line 1442  In the 16-bit version of this structure,
1442  "PCRE_UCHAR16 **".  "PCRE_UCHAR16 **".
1443  </P>  </P>
1444  <P>  <P>
1445  The <i>flags</i> field is a bitmap that specifies which of the other fields  The <i>flags</i> field is used to specify which of the other fields are set. The
1446  are set. The flag bits are:  flag bits are:
1447  <pre>  <pre>
1448    PCRE_EXTRA_STUDY_DATA    PCRE_EXTRA_CALLOUT_DATA
1449    PCRE_EXTRA_EXECUTABLE_JIT    PCRE_EXTRA_EXECUTABLE_JIT
1450      PCRE_EXTRA_MARK
1451    PCRE_EXTRA_MATCH_LIMIT    PCRE_EXTRA_MATCH_LIMIT
1452    PCRE_EXTRA_MATCH_LIMIT_RECURSION    PCRE_EXTRA_MATCH_LIMIT_RECURSION
1453    PCRE_EXTRA_CALLOUT_DATA    PCRE_EXTRA_STUDY_DATA
1454    PCRE_EXTRA_TABLES    PCRE_EXTRA_TABLES
   PCRE_EXTRA_MARK  
1455  </pre>  </pre>
1456  Other flag bits should be set to zero. The <i>study_data</i> field and sometimes  Other flag bits should be set to zero. The <i>study_data</i> field and sometimes
1457  the <i>executable_jit</i> field are set in the <b>pcre_extra</b> block that is  the <i>executable_jit</i> field are set in the <b>pcre_extra</b> block that is
1458  returned by <b>pcre_study()</b>, together with the appropriate flag bits. You  returned by <b>pcre_study()</b>, together with the appropriate flag bits. You
1459  should not set these yourself, but you may add to the block by setting the  should not set these yourself, but you may add to the block by setting other
1460  other fields and their corresponding flag bits.  fields and their corresponding flag bits.
1461  </P>  </P>
1462  <P>  <P>
1463  The <i>match_limit</i> field provides a means of preventing PCRE from using up a  The <i>match_limit</i> field provides a means of preventing PCRE from using up a
# Line 1472  in the subject string. Line 1475  in the subject string.
1475  </P>  </P>
1476  <P>  <P>
1477  When <b>pcre_exec()</b> is called with a pattern that was successfully studied  When <b>pcre_exec()</b> is called with a pattern that was successfully studied
1478  with the PCRE_STUDY_JIT_COMPILE option, the way that the matching is executed  with a JIT option, the way that the matching is executed is entirely different.
1479  is entirely different. However, there is still the possibility of runaway  However, there is still the possibility of runaway matching that goes on for a
1480  matching that goes on for a very long time, and so the <i>match_limit</i> value  very long time, and so the <i>match_limit</i> value is also used in this case
1481  is also used in this case (but in a different way) to limit how long the  (but in a different way) to limit how long the matching can continue.
 matching can continue.  
1482  </P>  </P>
1483  <P>  <P>
1484  The default value for the limit can be set when PCRE is built; the default  The default value for the limit can be set when PCRE is built; the default
# Line 1497  This limit is of use only if it is set s Line 1499  This limit is of use only if it is set s
1499  Limiting the recursion depth limits the amount of machine stack that can be  Limiting the recursion depth limits the amount of machine stack that can be
1500  used, or, when PCRE has been compiled to use memory on the heap instead of the  used, or, when PCRE has been compiled to use memory on the heap instead of the
1501  stack, the amount of heap memory that can be used. This limit is not relevant,  stack, the amount of heap memory that can be used. This limit is not relevant,
1502  and is ignored, if the pattern was successfully studied with  and is ignored, when matching is done using JIT compiled code.
 PCRE_STUDY_JIT_COMPILE.  
1503  </P>  </P>
1504  <P>  <P>
1505  The default value for <i>match_limit_recursion</i> can be set when PCRE is  The default value for <i>match_limit_recursion</i> can be set when PCRE is
# Line 1549  Option bits for pcre_exec() Line 1550  Option bits for pcre_exec()
1550  The unused bits of the <i>options</i> argument for <b>pcre_exec()</b> must be  The unused bits of the <i>options</i> argument for <b>pcre_exec()</b> must be
1551  zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_<i>xxx</i>,  zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_<i>xxx</i>,
1552  PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART,  PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART,
1553  PCRE_NO_START_OPTIMIZE, PCRE_NO_UTF8_CHECK, PCRE_PARTIAL_SOFT, and  PCRE_NO_START_OPTIMIZE, PCRE_NO_UTF8_CHECK, PCRE_PARTIAL_HARD, and
1554  PCRE_PARTIAL_HARD.  PCRE_PARTIAL_SOFT.
1555  </P>  </P>
1556  <P>  <P>
1557  If the pattern was successfully studied with the PCRE_STUDY_JIT_COMPILE option,  If the pattern was successfully studied with one of the just-in-time (JIT)
1558  the only supported options for JIT execution are PCRE_NO_UTF8_CHECK,  compile options, the only supported options for JIT execution are
1559  PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, and PCRE_NOTEMPTY_ATSTART. Note in  PCRE_NO_UTF8_CHECK, PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY,
1560  particular that partial matching is not supported. If an unsupported option is  PCRE_NOTEMPTY_ATSTART, PCRE_PARTIAL_HARD, and PCRE_PARTIAL_SOFT. If an
1561  used, JIT execution is disabled and the normal interpretive code in  unsupported option is used, JIT execution is disabled and the normal
1562  <b>pcre_exec()</b> is run.  interpretive code in <b>pcre_exec()</b> is run.
1563  <pre>  <pre>
1564    PCRE_ANCHORED    PCRE_ANCHORED
1565  </pre>  </pre>
# Line 1681  causing performance to suffer, but ensur Line 1682  causing performance to suffer, but ensur
1682  "no match", the callouts do occur, and that items such as (*COMMIT) and (*MARK)  "no match", the callouts do occur, and that items such as (*COMMIT) and (*MARK)
1683  are considered at every possible starting position in the subject string. If  are considered at every possible starting position in the subject string. If
1684  PCRE_NO_START_OPTIMIZE is set at compile time, it cannot be unset at matching  PCRE_NO_START_OPTIMIZE is set at compile time, it cannot be unset at matching
1685  time.  time. The use of PCRE_NO_START_OPTIMIZE disables JIT execution; when it is set,
1686    matching is always done using interpretively.
1687  </P>  </P>
1688  <P>  <P>
1689  Setting PCRE_NO_START_OPTIMIZE can change the outcome of a matching operation.  Setting PCRE_NO_START_OPTIMIZE can change the outcome of a matching operation.
# Line 2067  time. Line 2069  time.
2069  <pre>  <pre>
2070    PCRE_ERROR_JIT_STACKLIMIT (-27)    PCRE_ERROR_JIT_STACKLIMIT (-27)
2071  </pre>  </pre>
2072  This error is returned when a pattern that was successfully studied using the  This error is returned when a pattern that was successfully studied using a
2073  PCRE_STUDY_JIT_COMPILE option is being matched, but the memory available for  JIT compile option is being matched, but the memory available for the
2074  the just-in-time processing stack is not large enough. See the  just-in-time processing stack is not large enough. See the
2075  <a href="pcrejit.html"><b>pcrejit</b></a>  <a href="pcrejit.html"><b>pcrejit</b></a>
2076  documentation for more details.  documentation for more details.
2077  <pre>  <pre>
# Line 2599  Cambridge CB2 3QH, England. Line 2601  Cambridge CB2 3QH, England.
2601  </P>  </P>
2602  <br><a name="SEC26" href="#TOC1">REVISION</a><br>  <br><a name="SEC26" href="#TOC1">REVISION</a><br>
2603  <P>  <P>
2604  Last updated: 21 January 2012  Last updated: 22 February 2012
2605  <br>  <br>
2606  Copyright &copy; 1997-2012 University of Cambridge.  Copyright &copy; 1997-2012 University of Cambridge.
2607  <br>  <br>
Legend:
Removed from v.929  
changed lines
  Added in v.930
webmaster@exim.org
 ViewVC Help
Powered by ViewVC 1.1.12