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

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

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

revision 86 by nigel, Sat Feb 24 21:40:52 2007 UTC revision 87 by nigel, Sat Feb 24 21:41:21 2007 UTC
# Line 309  The output is an integer that gives the Line 309  The output is an integer that gives the
309  internal matching function calls in a \fBpcre_exec()\fP execution. Further  internal matching function calls in a \fBpcre_exec()\fP execution. Further
310  details are given with \fBpcre_exec()\fP below.  details are given with \fBpcre_exec()\fP below.
311  .sp  .sp
312      PCRE_CONFIG_MATCH_LIMIT_RECURSION
313    .sp
314    The output is an integer that gives the default limit for the depth of
315    recursion when calling the internal matching function in a \fBpcre_exec()\fP
316    execution. Further details are given with \fBpcre_exec()\fP below.
317    .sp
318    PCRE_CONFIG_STACKRECURSE    PCRE_CONFIG_STACKRECURSE
319  .sp  .sp
320  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 370  time. Line 376  time.
376  If \fIerrptr\fP is NULL, \fBpcre_compile()\fP returns NULL immediately.  If \fIerrptr\fP is NULL, \fBpcre_compile()\fP returns NULL immediately.
377  Otherwise, if compilation of a pattern fails, \fBpcre_compile()\fP returns  Otherwise, if compilation of a pattern fails, \fBpcre_compile()\fP returns
378  NULL, and sets the variable pointed to by \fIerrptr\fP to point to a textual  NULL, and sets the variable pointed to by \fIerrptr\fP to point to a textual
379  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
380  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
381    where the error was discovered is placed in the variable pointed to by
382  \fIerroffset\fP, which must not be NULL. If it is, an immediate error is given.  \fIerroffset\fP, which must not be NULL. If it is, an immediate error is given.
383  .P  .P
384  If \fBpcre_compile2()\fP is used instead of \fBpcre_compile()\fP, and the  If \fBpcre_compile2()\fP is used instead of \fBpcre_compile()\fP, and the
# Line 631  options are defined, and this argument s Line 638  options are defined, and this argument s
638  .P  .P
639  The third argument for \fBpcre_study()\fP is a pointer for an error message. If  The third argument for \fBpcre_study()\fP is a pointer for an error message. If
640  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
641  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
642  therefore test the error pointer for NULL after calling \fBpcre_study()\fP, to  static string that is part of the library. You must not try to free it. You
643  be sure that it has run successfully.  should test the error pointer for NULL after calling \fBpcre_study()\fP, to be
644    sure that it has run successfully.
645  .P  .P
646  This is a typical call to \fBpcre_study\fP():  This is a typical call to \fBpcre_study\fP():
647  .sp  .sp
# Line 657  digits, or whatever, by reference to a s Line 665  digits, or whatever, by reference to a s
665  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
666  less than 128. Higher-valued codes never match escapes such as \ew or \ed, but  less than 128. Higher-valued codes never match escapes such as \ew or \ed, but
667  can be tested with \ep if PCRE is built with Unicode character property  can be tested with \ep if PCRE is built with Unicode character property
668  support.  support. The use of locales with Unicode is discouraged.
669  .P  .P
670  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
671  built. This is used when the final argument of \fBpcre_compile()\fP is NULL,  built. This is used when the final argument of \fBpcre_compile()\fP is NULL,
# Line 964  Here is an example of a simple call to \ Line 972  Here is an example of a simple call to \
972  If the \fIextra\fP argument is not NULL, it must point to a \fBpcre_extra\fP  If the \fIextra\fP argument is not NULL, it must point to a \fBpcre_extra\fP
973  data block. The \fBpcre_study()\fP function returns such a block (when it  data block. The \fBpcre_study()\fP function returns such a block (when it
974  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
975  additional information in it. The fields in a \fBpcre_extra\fP block are as  additional information in it. The \fBpcre_extra\fP block contains the following
976  follows:  fields (not necessarily in this order):
977  .sp  .sp
978    unsigned long int \fIflags\fP;    unsigned long int \fIflags\fP;
979    void *\fIstudy_data\fP;    void *\fIstudy_data\fP;
980    unsigned long int \fImatch_limit\fP;    unsigned long int \fImatch_limit\fP;
981      unsigned long int \fImatch_limit_recursion\fP;
982    void *\fIcallout_data\fP;    void *\fIcallout_data\fP;
983    const unsigned char *\fItables\fP;    const unsigned char *\fItables\fP;
984  .sp  .sp
# Line 978  are set. The flag bits are: Line 987  are set. The flag bits are:
987  .sp  .sp
988    PCRE_EXTRA_STUDY_DATA    PCRE_EXTRA_STUDY_DATA
989    PCRE_EXTRA_MATCH_LIMIT    PCRE_EXTRA_MATCH_LIMIT
990      PCRE_EXTRA_MATCH_LIMIT_RECURSION
991    PCRE_EXTRA_CALLOUT_DATA    PCRE_EXTRA_CALLOUT_DATA
992    PCRE_EXTRA_TABLES    PCRE_EXTRA_TABLES
993  .sp  .sp
# Line 992  but which have a very large number of po Line 1002  but which have a very large number of po
1002  classic example is the use of nested unlimited repeats.  classic example is the use of nested unlimited repeats.
1003  .P  .P
1004  Internally, PCRE uses a function called \fBmatch()\fP which it calls repeatedly  Internally, PCRE uses a function called \fBmatch()\fP which it calls repeatedly
1005  (sometimes recursively). The limit is imposed on the number of times this  (sometimes recursively). The limit set by \fImatch_limit\fP is imposed on the
1006  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
1007  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
1008  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
1009    string.
1010  .P  .P
1011  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
1012  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
1013  reduce the default by suppling \fBpcre_exec()\fP with a \fBpcre_extra\fP block  override the default by suppling \fBpcre_exec()\fP with a \fBpcre_extra\fP
1014  in which \fImatch_limit\fP is set to a smaller value, and  block in which \fImatch_limit\fP is set, and PCRE_EXTRA_MATCH_LIMIT is set in
1015  PCRE_EXTRA_MATCH_LIMIT is set in the \fIflags\fP field. If the limit is  the \fIflags\fP field. If the limit is exceeded, \fBpcre_exec()\fP returns
1016  exceeded, \fBpcre_exec()\fP returns PCRE_ERROR_MATCHLIMIT.  PCRE_ERROR_MATCHLIMIT.
1017    .P
1018    The \fImatch_limit_recursion\fP field is similar to \fImatch_limit\fP, but
1019    instead of limiting the total number of times that \fBmatch()\fP is called, it
1020    limits the depth of recursion. The recursion depth is a smaller number than the
1021    total number of calls, because not all calls to \fBmatch()\fP are recursive.
1022    This limit is of use only if it is set smaller than \fImatch_limit\fP.
1023    .P
1024    Limiting the recursion depth limits the amount of stack that can be used, or,
1025    when PCRE has been compiled to use memory on the heap instead of the stack, the
1026    amount of heap memory that can be used.
1027    .P
1028    The default value for \fImatch_limit_recursion\fP can be set when PCRE is
1029    built; the default default is the same value as the default for
1030    \fImatch_limit\fP. You can override the default by suppling \fBpcre_exec()\fP
1031    with a \fBpcre_extra\fP block in which \fImatch_limit_recursion\fP is set, and
1032    PCRE_EXTRA_MATCH_LIMIT_RECURSION is set in the \fIflags\fP field. If the limit
1033    is exceeded, \fBpcre_exec()\fP returns PCRE_ERROR_RECURSIONLIMIT.
1034  .P  .P
1035  The \fIpcre_callout\fP field is used in conjunction with the "callout" feature,  The \fIpcre_callout\fP field is used in conjunction with the "callout" feature,
1036  which is described in the  which is described in the
# Line 1250  below). It is never returned by \fBpcre_ Line 1278  below). It is never returned by \fBpcre_
1278  .sp  .sp
1279    PCRE_ERROR_MATCHLIMIT     (-8)    PCRE_ERROR_MATCHLIMIT     (-8)
1280  .sp  .sp
1281  The recursion and backtracking limit, as specified by the \fImatch_limit\fP  The backtracking limit, as specified by the \fImatch_limit\fP field in a
1282    \fBpcre_extra\fP structure (or defaulted) was reached. See the description
1283    above.
1284    .sp
1285      PCRE_ERROR_RECURSIONLIMIT (-21)
1286    .sp
1287    The internal recursion limit, as specified by the \fImatch_limit_recursion\fP
1288  field in a \fBpcre_extra\fP structure (or defaulted) was reached. See the  field in a \fBpcre_extra\fP structure (or defaulted) was reached. See the
1289  description above.  description above.
1290  .sp  .sp
# Line 1499  vector should contain at least 20 elemen Line 1533  vector should contain at least 20 elemen
1533  multiple paths through the pattern tree. More workspace will be needed for  multiple paths through the pattern tree. More workspace will be needed for
1534  patterns and subjects where there are a lot of possible matches.  patterns and subjects where there are a lot of possible matches.
1535  .P  .P
1536  Here is an example of a simple call to \fBpcre_exec()\fP:  Here is an example of a simple call to \fBpcre_dfa_exec()\fP:
1537  .sp  .sp
1538    int rc;    int rc;
1539    int ovector[10];    int ovector[10];
1540    int wspace[20];    int wspace[20];
1541    rc = pcre_exec(    rc = pcre_dfa_exec(
1542      re,             /* result of pcre_compile() */      re,             /* result of pcre_compile() */
1543      NULL,           /* we didn't study the pattern */      NULL,           /* we didn't study the pattern */
1544      "some string",  /* the subject string */      "some string",  /* the subject string */
# Line 1631  error is given if the output vector is n Line 1665  error is given if the output vector is n
1665  extremely rare, as a vector of size 1000 is used.  extremely rare, as a vector of size 1000 is used.
1666  .P  .P
1667  .in 0  .in 0
1668  Last updated: 16 May 2005  Last updated: 18 January 2006
1669  .br  .br
1670  Copyright (c) 1997-2005 University of Cambridge.  Copyright (c) 1997-2006 University of Cambridge.
Legend:
Removed from v.86  
changed lines
  Added in v.87
webmaster@exim.org
 ViewVC Help
Powered by ViewVC 1.1.12