/[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 79 by nigel, Sat Feb 24 21:40:52 2007 UTC revision 87 by nigel, Sat Feb 24 21:41:21 2007 UTC
# Line 302  The output is an integer that gives the Line 302  The output is an integer that gives the
302  internal matching function calls in a <b>pcre_exec()</b> execution. Further  internal matching function calls in a <b>pcre_exec()</b> execution. Further
303  details are given with <b>pcre_exec()</b> below.  details are given with <b>pcre_exec()</b> below.
304  <pre>  <pre>
305      PCRE_CONFIG_MATCH_LIMIT_RECURSION
306    </pre>
307    The output is an integer that gives the default limit for the depth of
308    recursion when calling the internal matching function in a <b>pcre_exec()</b>
309    execution. Further details are given with <b>pcre_exec()</b> below.
310    <pre>
311    PCRE_CONFIG_STACKRECURSE    PCRE_CONFIG_STACKRECURSE
312  </pre>  </pre>
313  The output is an integer that is set to one if internal recursion when running  The output is an integer that is set to one if internal recursion when running
# Line 358  time. Line 364  time.
364  If <i>errptr</i> is NULL, <b>pcre_compile()</b> returns NULL immediately.  If <i>errptr</i> is NULL, <b>pcre_compile()</b> returns NULL immediately.
365  Otherwise, if compilation of a pattern fails, <b>pcre_compile()</b> returns  Otherwise, if compilation of a pattern fails, <b>pcre_compile()</b> returns
366  NULL, and sets the variable pointed to by <i>errptr</i> to point to a textual  NULL, and sets the variable pointed to by <i>errptr</i> to point to a textual
367  error message. The offset from the start of the pattern to the character where  error message. This is a static string that is part of the library. You must
368  the error was discovered is placed in the variable pointed to by  not try to free it. The offset from the start of the pattern to the character
369    where the error was discovered is placed in the variable pointed to by
370  <i>erroffset</i>, which must not be NULL. If it is, an immediate error is given.  <i>erroffset</i>, which must not be NULL. If it is, an immediate error is given.
371  </P>  </P>
372  <P>  <P>
# Line 615  options are defined, and this argument s Line 622  options are defined, and this argument s
622  <P>  <P>
623  The third argument for <b>pcre_study()</b> is a pointer for an error message. If  The third argument for <b>pcre_study()</b> is a pointer for an error message. If
624  studying succeeds (even if no data is returned), the variable it points to is  studying succeeds (even if no data is returned), the variable it points to is
625  set to NULL. Otherwise it points to a textual error message. You should  set to NULL. Otherwise it is set to point to a textual error message. This is a
626  therefore test the error pointer for NULL after calling <b>pcre_study()</b>, to  static string that is part of the library. You must not try to free it. You
627  be sure that it has run successfully.  should test the error pointer for NULL after calling <b>pcre_study()</b>, to be
628    sure that it has run successfully.
629  </P>  </P>
630  <P>  <P>
631  This is a typical call to <b>pcre_study</b>():  This is a typical call to <b>pcre_study</b>():
# Line 639  digits, or whatever, by reference to a s Line 647  digits, or whatever, by reference to a s
647  value. When running in UTF-8 mode, this applies only to characters with codes  value. When running in UTF-8 mode, this applies only to characters with codes
648  less than 128. Higher-valued codes never match escapes such as \w or \d, but  less than 128. Higher-valued codes never match escapes such as \w or \d, but
649  can be tested with \p if PCRE is built with Unicode character property  can be tested with \p if PCRE is built with Unicode character property
650  support.  support. The use of locales with Unicode is discouraged.
651  </P>  </P>
652  <P>  <P>
653  An internal set of tables is created in the default C locale when PCRE is  An internal set of tables is created in the default C locale when PCRE is
# Line 947  Extra data for <b>pcre_exec()</b> Line 955  Extra data for <b>pcre_exec()</b>
955  If the <i>extra</i> argument is not NULL, it must point to a <b>pcre_extra</b>  If the <i>extra</i> argument is not NULL, it must point to a <b>pcre_extra</b>
956  data block. The <b>pcre_study()</b> function returns such a block (when it  data block. The <b>pcre_study()</b> function returns such a block (when it
957  doesn't return NULL), but you can also create one for yourself, and pass  doesn't return NULL), but you can also create one for yourself, and pass
958  additional information in it. The fields in a <b>pcre_extra</b> block are as  additional information in it. The <b>pcre_extra</b> block contains the following
959  follows:  fields (not necessarily in this order):
960  <pre>  <pre>
961    unsigned long int <i>flags</i>;    unsigned long int <i>flags</i>;
962    void *<i>study_data</i>;    void *<i>study_data</i>;
963    unsigned long int <i>match_limit</i>;    unsigned long int <i>match_limit</i>;
964      unsigned long int <i>match_limit_recursion</i>;
965    void *<i>callout_data</i>;    void *<i>callout_data</i>;
966    const unsigned char *<i>tables</i>;    const unsigned char *<i>tables</i>;
967  </pre>  </pre>
# Line 961  are set. The flag bits are: Line 970  are set. The flag bits are:
970  <pre>  <pre>
971    PCRE_EXTRA_STUDY_DATA    PCRE_EXTRA_STUDY_DATA
972    PCRE_EXTRA_MATCH_LIMIT    PCRE_EXTRA_MATCH_LIMIT
973      PCRE_EXTRA_MATCH_LIMIT_RECURSION
974    PCRE_EXTRA_CALLOUT_DATA    PCRE_EXTRA_CALLOUT_DATA
975    PCRE_EXTRA_TABLES    PCRE_EXTRA_TABLES
976  </pre>  </pre>
# Line 977  classic example is the use of nested unl Line 987  classic example is the use of nested unl
987  </P>  </P>
988  <P>  <P>
989  Internally, PCRE uses a function called <b>match()</b> which it calls repeatedly  Internally, PCRE uses a function called <b>match()</b> which it calls repeatedly
990  (sometimes recursively). The limit is imposed on the number of times this  (sometimes recursively). The limit set by <i>match_limit</i> is imposed on the
991  function is called during a match, which has the effect of limiting the amount  number of times this function is called during a match, which has the effect of
992  of recursion and backtracking that can take place. For patterns that are not  limiting the amount of backtracking that can take place. For patterns that are
993  anchored, the count starts from zero for each position in the subject string.  not anchored, the count restarts from zero for each position in the subject
994    string.
995  </P>  </P>
996  <P>  <P>
997  The default limit for the library can be set when PCRE is built; the default  The default value for the limit can be set when PCRE is built; the default
998  default is 10 million, which handles all but the most extreme cases. You can  default is 10 million, which handles all but the most extreme cases. You can
999  reduce the default by suppling <b>pcre_exec()</b> with a <b>pcre_extra</b> block  override the default by suppling <b>pcre_exec()</b> with a <b>pcre_extra</b>
1000  in which <i>match_limit</i> is set to a smaller value, and  block in which <i>match_limit</i> is set, and PCRE_EXTRA_MATCH_LIMIT is set in
1001  PCRE_EXTRA_MATCH_LIMIT is set in the <i>flags</i> field. If the limit is  the <i>flags</i> field. If the limit is exceeded, <b>pcre_exec()</b> returns
1002  exceeded, <b>pcre_exec()</b> returns PCRE_ERROR_MATCHLIMIT.  PCRE_ERROR_MATCHLIMIT.
1003    </P>
1004    <P>
1005    The <i>match_limit_recursion</i> field is similar to <i>match_limit</i>, but
1006    instead of limiting the total number of times that <b>match()</b> is called, it
1007    limits the depth of recursion. The recursion depth is a smaller number than the
1008    total number of calls, because not all calls to <b>match()</b> are recursive.
1009    This limit is of use only if it is set smaller than <i>match_limit</i>.
1010    </P>
1011    <P>
1012    Limiting the recursion depth limits the amount of stack that can be used, or,
1013    when PCRE has been compiled to use memory on the heap instead of the stack, the
1014    amount of heap memory that can be used.
1015    </P>
1016    <P>
1017    The default value for <i>match_limit_recursion</i> can be set when PCRE is
1018    built; the default default is the same value as the default for
1019    <i>match_limit</i>. You can override the default by suppling <b>pcre_exec()</b>
1020    with a <b>pcre_extra</b> block in which <i>match_limit_recursion</i> is set, and
1021    PCRE_EXTRA_MATCH_LIMIT_RECURSION is set in the <i>flags</i> field. If the limit
1022    is exceeded, <b>pcre_exec()</b> returns PCRE_ERROR_RECURSIONLIMIT.
1023  </P>  </P>
1024  <P>  <P>
1025  The <i>pcre_callout</i> field is used in conjunction with the "callout" feature,  The <i>pcre_callout</i> field is used in conjunction with the "callout" feature,
# Line 1247  below). It is never returned by <b>pcre_ Line 1278  below). It is never returned by <b>pcre_
1278  <pre>  <pre>
1279    PCRE_ERROR_MATCHLIMIT     (-8)    PCRE_ERROR_MATCHLIMIT     (-8)
1280  </pre>  </pre>
1281  The recursion and backtracking limit, as specified by the <i>match_limit</i>  The backtracking limit, as specified by the <i>match_limit</i> field in a
1282    <b>pcre_extra</b> structure (or defaulted) was reached. See the description
1283    above.
1284    <pre>
1285      PCRE_ERROR_RECURSIONLIMIT (-21)
1286    </pre>
1287    The internal recursion limit, as specified by the <i>match_limit_recursion</i>
1288  field in a <b>pcre_extra</b> structure (or defaulted) was reached. See the  field in a <b>pcre_extra</b> structure (or defaulted) was reached. See the
1289  description above.  description above.
1290  <pre>  <pre>
# Line 1478  multiple paths through the pattern tree. Line 1515  multiple paths through the pattern tree.
1515  patterns and subjects where there are a lot of possible matches.  patterns and subjects where there are a lot of possible matches.
1516  </P>  </P>
1517  <P>  <P>
1518  Here is an example of a simple call to <b>pcre_exec()</b>:  Here is an example of a simple call to <b>pcre_dfa_exec()</b>:
1519  <pre>  <pre>
1520    int rc;    int rc;
1521    int ovector[10];    int ovector[10];
1522    int wspace[20];    int wspace[20];
1523    rc = pcre_exec(    rc = pcre_dfa_exec(
1524      re,             /* result of pcre_compile() */      re,             /* result of pcre_compile() */
1525      NULL,           /* we didn't study the pattern */      NULL,           /* we didn't study the pattern */
1526      "some string",  /* the subject string */      "some string",  /* the subject string */
# Line 1610  error is given if the output vector is n Line 1647  error is given if the output vector is n
1647  extremely rare, as a vector of size 1000 is used.  extremely rare, as a vector of size 1000 is used.
1648  </P>  </P>
1649  <P>  <P>
1650  Last updated: 16 May 2005  Last updated: 18 January 2006
1651  <br>  <br>
1652  Copyright &copy; 1997-2005 University of Cambridge.  Copyright &copy; 1997-2006 University of Cambridge.
1653  <p>  <p>
1654  Return to the <a href="index.html">PCRE index page</a>.  Return to the <a href="index.html">PCRE index page</a>.
1655  </p>  </p>
Legend:
Removed from v.79  
changed lines
  Added in v.87
  ViewVC Help
Powered by ViewVC 1.1.5