/[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 455 by ph10, Sat Sep 26 19:12:32 2009 UTC revision 456 by ph10, Fri Oct 2 08:53:31 2009 UTC
# Line 395  avoiding the use of the stack. Line 395  avoiding the use of the stack.
395  Either of the functions \fBpcre_compile()\fP or \fBpcre_compile2()\fP can be  Either of the functions \fBpcre_compile()\fP or \fBpcre_compile2()\fP can be
396  called to compile a pattern into an internal form. The only difference between  called to compile a pattern into an internal form. The only difference between
397  the two interfaces is that \fBpcre_compile2()\fP has an additional argument,  the two interfaces is that \fBpcre_compile2()\fP has an additional argument,
398  \fIerrorcodeptr\fP, via which a numerical error code can be returned.  \fIerrorcodeptr\fP, via which a numerical error code can be returned. To avoid
399    too much repetition, we refer just to \fBpcre_compile()\fP below, but the
400    information applies equally to \fBpcre_compile2()\fP.
401  .P  .P
402  The pattern is a C string terminated by a binary zero, and is passed in the  The pattern is a C string terminated by a binary zero, and is passed in the
403  \fIpattern\fP argument. A pointer to a single block of memory that is obtained  \fIpattern\fP argument. A pointer to a single block of memory that is obtained
# Line 412  argument, which is an address (see below Line 414  argument, which is an address (see below
414  The \fIoptions\fP argument contains various bit settings that affect the  The \fIoptions\fP argument contains various bit settings that affect the
415  compilation. It should be zero if no options are required. The available  compilation. It should be zero if no options are required. The available
416  options are described below. Some of them (in particular, those that are  options are described below. Some of them (in particular, those that are
417  compatible with Perl, but also some others) can also be set and unset from  compatible with Perl, but some others as well) can also be set and unset from
418  within the pattern (see the detailed description in the  within the pattern (see the detailed description in the
419  .\" HREF  .\" HREF
420  \fBpcrepattern\fP  \fBpcrepattern\fP
421  .\"  .\"
422  documentation). For those options that can be different in different parts of  documentation). For those options that can be different in different parts of
423  the pattern, the contents of the \fIoptions\fP argument specifies their initial  the pattern, the contents of the \fIoptions\fP argument specifies their
424  settings at the start of compilation and execution. The PCRE_ANCHORED and  settings at the start of compilation and execution. The PCRE_ANCHORED,
425  PCRE_NEWLINE_\fIxxx\fP options can be set at the time of matching as well as at  PCRE_BSR_\fIxxx\fP, and PCRE_NEWLINE_\fIxxx\fP options can be set at the time
426  compile time.  of matching as well as at compile time.
427  .P  .P
428  If \fIerrptr\fP is NULL, \fBpcre_compile()\fP returns NULL immediately.  If \fIerrptr\fP is NULL, \fBpcre_compile()\fP returns NULL immediately.
429  Otherwise, if compilation of a pattern fails, \fBpcre_compile()\fP returns  Otherwise, if compilation of a pattern fails, \fBpcre_compile()\fP returns
430  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
431  error message. This is a static string that is part of the library. You must  error message. This is a static string that is part of the library. You must
432  not try to free it. The byte offset from the start of the pattern to the  not try to free it. The byte offset from the start of the pattern to the
433  character that was being processes when the error was discovered is placed in  character that was being processed when the error was discovered is placed in
434  the variable pointed to by \fIerroffset\fP, which must not be NULL. If it is,  the variable pointed to by \fIerroffset\fP, which must not be NULL. If it is,
435  an immediate error is given. Some errors are not detected until checks are  an immediate error is given. Some errors are not detected until checks are
436  carried out when the whole pattern has been scanned; in this case the offset is  carried out when the whole pattern has been scanned; in this case the offset is
# Line 984  is -1. Line 986  is -1.
986  .sp  .sp
987  If the pattern was studied and a minimum length for matching subject strings  If the pattern was studied and a minimum length for matching subject strings
988  was computed, its value is returned. Otherwise the returned value is -1. The  was computed, its value is returned. Otherwise the returned value is -1. The
989  value is a number of characters, not bytes (there may be a difference in UTF-8  value is a number of characters, not bytes (this may be relevant in UTF-8
990  mode). The fourth argument should point to an \fBint\fP variable. A  mode). The fourth argument should point to an \fBint\fP variable. A
991  non-negative value is a lower bound to the length of any matching string. There  non-negative value is a lower bound to the length of any matching string. There
992  may not be any strings of that length that do actually match, but every string  may not be any strings of that length that do actually match, but every string
# Line 1209  the block by setting the other fields an Line 1211  the block by setting the other fields an
1211  The \fImatch_limit\fP field provides a means of preventing PCRE from using up a  The \fImatch_limit\fP field provides a means of preventing PCRE from using up a
1212  vast amount of resources when running patterns that are not going to match,  vast amount of resources when running patterns that are not going to match,
1213  but which have a very large number of possibilities in their search trees. The  but which have a very large number of possibilities in their search trees. The
1214  classic example is the use of nested unlimited repeats.  classic example is a pattern that uses nested unlimited repeats.
1215  .P  .P
1216  Internally, PCRE uses a function called \fBmatch()\fP which it calls repeatedly  Internally, PCRE uses a function called \fBmatch()\fP which it calls repeatedly
1217  (sometimes recursively). The limit set by \fImatch_limit\fP is imposed on the  (sometimes recursively). The limit set by \fImatch_limit\fP is imposed on the
# Line 1508  the \fIovector\fP is not big enough to r Line 1510  the \fIovector\fP is not big enough to r
1510  has to get additional memory for use during matching. Thus it is usually  has to get additional memory for use during matching. Thus it is usually
1511  advisable to supply an \fIovector\fP.  advisable to supply an \fIovector\fP.
1512  .P  .P
1513  The \fBpcre_info()\fP function can be used to find out how many capturing  The \fBpcre_fullinfo()\fP function can be used to find out how many capturing
1514  subpatterns there are in a compiled pattern. The smallest size for  subpatterns there are in a compiled pattern. The smallest size for
1515  \fIovector\fP that will allow for \fIn\fP captured substrings, in addition to  \fIovector\fP that will allow for \fIn\fP captured substrings, in addition to
1516  the offsets of the substring matched by the whole pattern, is (\fIn\fP+1)*3.  the offsets of the substring matched by the whole pattern, is (\fIn\fP+1)*3.
# Line 2043  Cambridge CB2 3QH, England. Line 2045  Cambridge CB2 3QH, England.
2045  .rs  .rs
2046  .sp  .sp
2047  .nf  .nf
2048  Last updated: 26 September 2009  Last updated: 29 September 2009
2049  Copyright (c) 1997-2009 University of Cambridge.  Copyright (c) 1997-2009 University of Cambridge.
2050  .fi  .fi

Legend:
Removed from v.455  
changed lines
  Added in v.456

  ViewVC Help
Powered by ViewVC 1.1.5