diff -r 000000000000 -r 7f656887cf89 libraries/spcre/libpcre/pcre/doc/pcrestack.3 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/libraries/spcre/libpcre/pcre/doc/pcrestack.3 Wed Jun 23 15:52:26 2010 +0100 @@ -0,0 +1,160 @@ +.TH PCRESTACK 3 +.SH NAME +PCRE - Perl-compatible regular expressions +.SH "PCRE DISCUSSION OF STACK USAGE" +.rs +.sp +When you call \fBpcre_exec()\fP, it makes use of an internal function called +\fBmatch()\fP. This calls itself recursively at branch points in the pattern, +in order to remember the state of the match so that it can back up and try a +different alternative if the first one fails. As matching proceeds deeper and +deeper into the tree of possibilities, the recursion depth increases. +.P +Not all calls of \fBmatch()\fP increase the recursion depth; for an item such +as a* it may be called several times at the same level, after matching +different numbers of a's. Furthermore, in a number of cases where the result of +the recursive call would immediately be passed back as the result of the +current call (a "tail recursion"), the function is just restarted instead. +.P +The \fBpcre_dfa_exec()\fP function operates in an entirely different way, and +hardly uses recursion at all. The limit on its complexity is the amount of +workspace it is given. The comments that follow do NOT apply to +\fBpcre_dfa_exec()\fP; they are relevant only for \fBpcre_exec()\fP. +.P +You can set limits on the number of times that \fBmatch()\fP is called, both in +total and recursively. If the limit is exceeded, an error occurs. For details, +see the +.\" HTML +.\" +section on extra data for \fBpcre_exec()\fP +.\" +in the +.\" HREF +\fBpcreapi\fP +.\" +documentation. +.P +Each time that \fBmatch()\fP is actually called recursively, it uses memory +from the process stack. For certain kinds of pattern and data, very large +amounts of stack may be needed, despite the recognition of "tail recursion". +You can often reduce the amount of recursion, and therefore the amount of stack +used, by modifying the pattern that is being matched. Consider, for example, +this pattern: +.sp + ([^<]|<(?!inet))+ +.sp +It matches from wherever it starts until it encounters " +.\" +http://developer.apple.com/qa/qa2005/qa1419.html. +.\" +. +. +.SH AUTHOR +.rs +.sp +.nf +Philip Hazel +University Computing Service +Cambridge CB2 3QH, England. +.fi +. +. +.SH REVISION +.rs +.sp +.nf +Last updated: 09 July 2008 +Copyright (c) 1997-2008 University of Cambridge. +.fi