/[pcre]/code/trunk/doc/pcre.txt

Diff of /code/trunk/doc/pcre.txt

Parent Directory | Revision Log | View Patch Patch

-revision 172 by ph10,
Tue Jun  5 10:40:13 2007 UTC
+revision 202 by ph10,
Fri Aug  3 09:44:26 2007 UTC
 Line 114 
 LIMITATIONS
         There is no limit to the number of parenthesized subpatterns, but there
         can be no more than 65535 capturing subpatterns.
+        If  a  non-capturing subpattern with an unlimited repetition quantifier
+        can match an empty string, there is a limit of 1000 on  the  number  of
+        times  it  can  be  repeated while not matching an empty string - if it
+        does match an empty string, the loop is immediately broken.
         The maximum length of name for a named subpattern is 32 characters, and
         the maximum number of named subpatterns is 10000.
-        The maximum length of a subject string is the largest  positive  number
+        The  maximum  length of a subject string is the largest positive number
-        that  an integer variable can hold. However, when using the traditional
+        that an integer variable can hold. However, when using the  traditional
         matching function, PCRE uses recursion to handle subpatterns and indef-
-        inite  repetition.  This means that the available stack space may limit
+        inite repetition.  This means that the available stack space may  limit
         the size of a subject string that can be processed by certain patterns.
         For a discussion of stack issues, see the pcrestack documentation.
  UTF-8 AND UNICODE PROPERTY SUPPORT
-        From  release  3.3,  PCRE  has  had  some support for character strings
+        From release 3.3, PCRE has  had  some  support  for  character  strings
-        encoded in the UTF-8 format. For release 4.0 this was greatly  extended
+        encoded  in the UTF-8 format. For release 4.0 this was greatly extended
-        to  cover  most common requirements, and in release 5.0 additional sup-
+        to cover most common requirements, and in release 5.0  additional  sup-
         port for Unicode general category properties was added.
-        In order process UTF-8 strings, you must build PCRE  to  include  UTF-8
+        In  order  process  UTF-8 strings, you must build PCRE to include UTF-8
-        support  in  the  code,  and, in addition, you must call pcre_compile()
+        support in the code, and, in addition,  you  must  call  pcre_compile()
-        with the PCRE_UTF8 option flag. When you do this, both the pattern  and
+        with  the PCRE_UTF8 option flag. When you do this, both the pattern and
-        any  subject  strings  that are matched against it are treated as UTF-8
+        any subject strings that are matched against it are  treated  as  UTF-8
         strings instead of just strings of bytes.
-        If you compile PCRE with UTF-8 support, but do not use it at run  time,
+        If  you compile PCRE with UTF-8 support, but do not use it at run time,
-        the  library will be a bit bigger, but the additional run time overhead
+        the library will be a bit bigger, but the additional run time  overhead
         is limited to testing the PCRE_UTF8 flag occasionally, so should not be
         very big.
         If PCRE is built with Unicode character property support (which implies
-        UTF-8 support), the escape sequences \p{..}, \P{..}, and  \X  are  sup-
+        UTF-8  support),  the  escape sequences \p{..}, \P{..}, and \X are sup-
         ported.  The available properties that can be tested are limited to the
-        general category properties such as Lu for an upper case letter  or  Nd
+        general  category  properties such as Lu for an upper case letter or Nd
-        for  a  decimal number, the Unicode script names such as Arabic or Han,
+        for a decimal number, the Unicode script names such as Arabic  or  Han,
-        and the derived properties Any and L&. A full  list  is  given  in  the
+        and  the  derived  properties  Any  and L&. A full list is given in the
         pcrepattern documentation. Only the short names for properties are sup-
-        ported. For example, \p{L} matches a letter. Its Perl synonym,  \p{Let-
+        ported.  For example, \p{L} matches a letter. Its Perl synonym, \p{Let-
-        ter},  is  not  supported.   Furthermore,  in Perl, many properties may
+        ter}, is not supported.  Furthermore,  in  Perl,  many  properties  may
-        optionally be prefixed by "Is", for compatibility with Perl  5.6.  PCRE
+        optionally  be  prefixed by "Is", for compatibility with Perl 5.6. PCRE
         does not support this.
         The following comments apply when PCRE is running in UTF-8 mode:
-.  When you set the PCRE_UTF8 flag, the strings passed as patterns and
+. When you set the PCRE_UTF8 flag, the strings passed as patterns  and
-        subjects are checked for validity on entry to the  relevant  functions.
+        subjects  are  checked for validity on entry to the relevant functions.
         If an invalid UTF-8 string is passed, an error return is given. In some
-        situations, you may already know  that  your  strings  are  valid,  and
+        situations,  you  may  already  know  that  your strings are valid, and
         therefore want to skip these checks in order to improve performance. If
-        you set the PCRE_NO_UTF8_CHECK flag at compile time  or  at  run  time,
+        you  set  the  PCRE_NO_UTF8_CHECK  flag at compile time or at run time,
-        PCRE  assumes  that  the  pattern or subject it is given (respectively)
+        PCRE assumes that the pattern or subject  it  is  given  (respectively)
-        contains only valid UTF-8 codes. In this case, it does not diagnose  an
+        contains  only valid UTF-8 codes. In this case, it does not diagnose an
-        invalid  UTF-8 string. If you pass an invalid UTF-8 string to PCRE when
+        invalid UTF-8 string. If you pass an invalid UTF-8 string to PCRE  when
-        PCRE_NO_UTF8_CHECK is set, the results are undefined. Your program  may
+        PCRE_NO_UTF8_CHECK  is set, the results are undefined. Your program may
         crash.
-.  An  unbraced  hexadecimal  escape sequence (such as \xb3) matches a
+. An unbraced hexadecimal escape sequence (such  as  \xb3)  matches  a
         two-byte UTF-8 character if the value is greater than 127.
-. Octal numbers up to \777 are recognized, and  match  two-byte  UTF-8
+.  Octal  numbers  up to \777 are recognized, and match two-byte UTF-8
         characters for values greater than \177.
-.  Repeat quantifiers apply to complete UTF-8 characters, not to indi-
+. Repeat quantifiers apply to complete UTF-8 characters, not to  indi-
         vidual bytes, for example: \x{100}{3}.
-. The dot metacharacter matches one UTF-8 character instead of a  sin-
+.  The dot metacharacter matches one UTF-8 character instead of a sin-
         gle byte.
-.  The  escape sequence \C can be used to match a single byte in UTF-8
+. The escape sequence \C can be used to match a single byte  in  UTF-8
-        mode, but its use can lead to some strange effects.  This  facility  is
+        mode,  but  its  use can lead to some strange effects. This facility is
         not available in the alternative matching function, pcre_dfa_exec().
-.  The  character escapes \b, \B, \d, \D, \s, \S, \w, and \W correctly
+. The character escapes \b, \B, \d, \D, \s, \S, \w, and  \W  correctly
-        test characters of any code value, but the characters that PCRE  recog-
+        test  characters of any code value, but the characters that PCRE recog-
-        nizes  as  digits,  spaces,  or  word characters remain the same set as
+        nizes as digits, spaces, or word characters  remain  the  same  set  as
         before, all with values less than 256. This remains true even when PCRE
-        includes  Unicode  property support, because to do otherwise would slow
+        includes Unicode property support, because to do otherwise  would  slow
-        down PCRE in many common cases. If you really want to test for a  wider
+        down  PCRE in many common cases. If you really want to test for a wider
-        sense  of,  say,  "digit",  you must use Unicode property tests such as
+        sense of, say, "digit", you must use Unicode  property  tests  such  as
         \p{Nd}.
-. Similarly, characters that match the POSIX named  character  classes
+.  Similarly,  characters that match the POSIX named character classes
         are all low-valued characters.
-.  Case-insensitive  matching  applies only to characters whose values
+. However, the Perl 5.10 horizontal and vertical  whitespace  matching
-        are less than 128, unless PCRE is built with Unicode property  support.
+        escapes (\h, \H, \v, and \V) do match all the appropriate Unicode char-
-        Even  when  Unicode  property support is available, PCRE still uses its
+        acters.
-        own character tables when checking the case of  low-valued  characters,
-        so  as not to degrade performance.  The Unicode property information is
+. Case-insensitive matching applies only to characters  whose  values
+        are  less than 128, unless PCRE is built with Unicode property support.
+        Even when Unicode property support is available, PCRE  still  uses  its
+        own  character  tables when checking the case of low-valued characters,
+        so as not to degrade performance.  The Unicode property information  is
         used only for characters with higher values. Even when Unicode property
         support is available, PCRE supports case-insensitive matching only when
-        there is a one-to-one mapping between a letter's  cases.  There  are  a
+        there  is  a  one-to-one  mapping between a letter's cases. There are a
-        small  number  of  many-to-one  mappings in Unicode; these are not sup-
+        small number of many-to-one mappings in Unicode;  these  are  not  sup-
         ported by PCRE.
-Line 215 
 AUTHOR
+Line 224 
 AUTHOR
         University Computing Service
         Cambridge CB2 3QH, England.
-        Putting an actual email address here seems to have been a spam  magnet,
+        Putting  an actual email address here seems to have been a spam magnet,
-        so  I've  taken  it away. If you want to email me, use my two initials,
+        so I've taken it away. If you want to email me, use  my  two  initials,
         followed by the two digits 10, at the domain cam.ac.uk.
  REVISION
-        Last updated: 18 April 2007
+        Last updated: 30 July 2007
         Copyright (c) 1997-2007 University of Cambridge.
  ------------------------------------------------------------------------------
-Line 390 
 AVOIDING EXCESSIVE STACK USAGE
+Line 399 
 AVOIDING EXCESSIVE STACK USAGE
         to  the  configure  command. With this configuration, PCRE will use the
         pcre_stack_malloc and pcre_stack_free variables to call memory  manage-
-        ment  functions.  Separate  functions are provided because the usage is
+        ment  functions. By default these point to malloc() and free(), but you
-        very predictable: the block sizes requested are always  the  same,  and
+        can replace the pointers so that your own functions are used.
-        the  blocks  are always freed in reverse order. A calling program might
-        be able to implement optimized functions that perform better  than  the
+        Separate functions are  provided  rather  than  using  pcre_malloc  and
-        standard  malloc()  and  free()  functions.  PCRE  runs noticeably more
+        pcre_free  because  the  usage  is  very  predictable:  the block sizes
-        slowly when built in this way. This option affects only the pcre_exec()
+        requested are always the same, and  the  blocks  are  always  freed  in
-        function; it is not relevant for the the pcre_dfa_exec() function.
+        reverse  order.  A calling program might be able to implement optimized
+        functions that perform better  than  malloc()  and  free().  PCRE  runs
+        noticeably more slowly when built in this way. This option affects only
+        the  pcre_exec()  function;  it   is   not   relevant   for   the   the
+        pcre_dfa_exec() function.
  LIMITING PCRE RESOURCE USAGE
-Line 451 
 USING EBCDIC CODE
+Line 464 
 USING EBCDIC CODE
         PCRE  assumes  by  default that it will run in an environment where the
         character code is ASCII (or Unicode, which is  a  superset  of  ASCII).
-        PCRE  can,  however,  be  compiled  to  run in an EBCDIC environment by
+        This  is  the  case for most computer operating systems. PCRE can, how-
-        adding
+        ever, be compiled to run in an EBCDIC environment by adding
           --enable-ebcdic
         to the configure command. This setting implies --enable-rebuild-charta-
-        bles.
+        bles.  You  should  only  use  it if you know that you are in an EBCDIC
+        environment (for example, an IBM mainframe operating system).
  SEE ALSO
-Line 474 
 AUTHOR
+Line 488 
 AUTHOR
  REVISION
-        Last updated: 16 April 2007
+        Last updated: 30 July 2007
         Copyright (c) 1997-2007 University of Cambridge.
  ------------------------------------------------------------------------------
-Line 1259 
 COMPILATION ERROR CODES
+Line 1273 
 COMPILATION ERROR CODES
  malformed number or name after (?(
  conditional group contains more than two branches
  assertion expected after (?(
- (?R or (?digits must be followed by )
+ (?R or (?[+-]digits must be followed by )
  unknown POSIX class name
  POSIX collating elements are not supported
  this version of PCRE is not compiled with PCRE_UTF8 support
-Line 1280 
 COMPILATION ERROR CODES
+Line 1294 
 COMPILATION ERROR CODES
  unknown property name after \P or \p
  subpattern name is too long (maximum 32 characters)
  too many named subpatterns (maximum 10,000)
- repeated subpattern is too long
+ [this code is not in use]
  octal value is greater than \377 (not in UTF-8 mode)
  internal error: overran compiling workspace
   internal  error:  previously-checked  referenced  subpattern not
-Line 1288 
 COMPILATION ERROR CODES
+Line 1302 
 COMPILATION ERROR CODES
  DEFINE group contains more than one branch
  repeating a DEFINE group is not allowed
  inconsistent NEWLINE options"
+ \g is not followed by a braced name or an optionally braced
+                non-zero number
+ (?+ or (?- or (?(+ or (?(- must be followed by a non-zero number
  STUDYING A PATTERN
-Line 1480 
 INFORMATION ABOUT A PATTERN
+Line 1497 
 INFORMATION ABOUT A PATTERN
         Return  1  if the (?J) option setting is used in the pattern, otherwise
 . The fourth argument should point to an int variable. The (?J) inter-
-        nal option setting changes the local PCRE_DUPNAMES value.
+        nal option setting changes the local PCRE_DUPNAMES option.
           PCRE_INFO_LASTLITERAL
-Line 1548 
 INFORMATION ABOUT A PATTERN
+Line 1565 
 INFORMATION ABOUT A PATTERN
         Return a copy of the options with which the pattern was  compiled.  The
         fourth  argument  should  point to an unsigned long int variable. These
         option bits are those specified in the call to pcre_compile(), modified
-        by any top-level option settings within the pattern itself.
+        by any top-level option settings at the start of the pattern itself. In
+        other words, they are the options that will be in force  when  matching
+        starts.  For  example, if the pattern /(?im)abc(?-i)d/ is compiled with
+        the PCRE_EXTENDED option, the result is PCRE_CASELESS,  PCRE_MULTILINE,
+        and PCRE_EXTENDED.
         A  pattern  is  automatically  anchored by PCRE if all of its top-level
         alternatives begin with one of the following:
-Line 2039 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
+Line 2060 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
         field  in  a  pcre_extra  structure (or defaulted) was reached. See the
         description above.
-          PCRE_ERROR_NULLWSLIMIT    (-22)
-        When a group that can match an empty  substring  is  repeated  with  an
-        unbounded  upper  limit, the subject position at the start of the group
-        must be remembered, so that a test for an empty string can be made when
-        the  end  of the group is reached. Some workspace is required for this;
-        if it runs out, this error is given.
           PCRE_ERROR_BADNEWLINE     (-23)
         An invalid combination of PCRE_NEWLINE_xxx options was given.
-        Error numbers -16 to -20 are not used by pcre_exec().
+        Error numbers -16 to -20 and -22 are not used by pcre_exec().
  EXTRACTING CAPTURED SUBSTRINGS BY NUMBER
-Line 2406 
 AUTHOR
+Line 2419 
 AUTHOR
  REVISION
-        Last updated: 04 June 2007
+        Last updated: 30 July 2007
         Copyright (c) 1997-2007 University of Cambridge.
  ------------------------------------------------------------------------------
-Line 2593 
 DIFFERENCES BETWEEN PCRE AND PERL
+Line 2606 
 DIFFERENCES BETWEEN PCRE AND PERL
         This  document describes the differences in the ways that PCRE and Perl
         handle regular expressions. The differences described here  are  mainly
-        with  respect  to  Perl 5.8, though PCRE version 7.0 contains some fea-
+        with  respect  to  Perl 5.8, though PCRE versions 7.0 and later contain
-        tures that are expected to be in the forthcoming Perl 5.10.
+        some features that are expected to be in the forthcoming Perl 5.10.
 . PCRE has only a subset of Perl's UTF-8 and Unicode support.  Details
         of  what  it does have are given in the section on UTF-8 support in the
-Line 2672 
 DIFFERENCES BETWEEN PCRE AND PERL
+Line 2685 
 DIFFERENCES BETWEEN PCRE AND PERL
         meta-character matches only at the very end of the string.
         (c) If PCRE_EXTRA is set, a backslash followed by a letter with no spe-
-        cial  meaning  is  faulted.  Otherwise,  like  Perl,  the  backslash is
+        cial meaning is faulted. Otherwise, like Perl, the backslash is quietly
-        ignored. (Perl can be made to issue a warning.)
+        ignored.  (Perl can be made to issue a warning.)
         (d) If PCRE_UNGREEDY is set, the greediness of the  repetition  quanti-
         fiers is inverted, that is, by default they are not greedy, but if fol-
-Line 2705 
 AUTHOR
+Line 2718 
 AUTHOR
  REVISION
-        Last updated: 06 March 2007
+        Last updated: 13 June 2007
         Copyright (c) 1997-2007 University of Cambridge.
  ------------------------------------------------------------------------------
-Line 2938 
 BACKSLASH
+Line 2951 
 BACKSLASH
           \d     any decimal digit
           \D     any character that is not a decimal digit
+          \h     any horizontal whitespace character
+          \H     any character that is not a horizontal whitespace character
           \s     any whitespace character
           \S     any character that is not a whitespace character
+          \v     any vertical whitespace character
+          \V     any character that is not a vertical whitespace character
           \w     any "word" character
           \W     any "non-word" character
-Line 2954 
 BACKSLASH
+Line 2971 
 BACKSLASH
         For compatibility with Perl, \s does not match the VT  character  (code
 ).   This makes it different from the the POSIX "space" class. The \s
-        characters are HT (9), LF (10), FF (12), CR (13), and space  (32).  (If
+        characters are HT (9), LF (10), FF (12), CR (13), and  space  (32).  If
         "use locale;" is included in a Perl script, \s may match the VT charac-
-        ter. In PCRE, it never does.)
+        ter. In PCRE, it never does.
+        In UTF-8 mode, characters with values greater than 128 never match  \d,
+        \s, or \w, and always match \D, \S, and \W. This is true even when Uni-
+        code character property support is available.  These  sequences  retain
+        their original meanings from before UTF-8 support was available, mainly
+        for efficiency reasons.
+        The sequences \h, \H, \v, and \V are Perl 5.10 features. In contrast to
+        the  other  sequences, these do match certain high-valued codepoints in
+        UTF-8 mode.  The horizontal space characters are:
+          U+0009     Horizontal tab
+          U+0020     Space
+          U+00A0     Non-break space
+          U+1680     Ogham space mark
+          U+180E     Mongolian vowel separator
+          U+2000     En quad
+          U+2001     Em quad
+          U+2002     En space
+          U+2003     Em space
+          U+2004     Three-per-em space
+          U+2005     Four-per-em space
+          U+2006     Six-per-em space
+          U+2007     Figure space
+          U+2008     Punctuation space
+          U+2009     Thin space
+          U+200A     Hair space
+          U+202F     Narrow no-break space
+          U+205F     Medium mathematical space
+          U+3000     Ideographic space
+        The vertical space characters are:
+          U+000A     Linefeed
+          U+000B     Vertical tab
+          U+000C     Formfeed
+          U+000D     Carriage return
+          U+0085     Next line
+          U+2028     Line separator
+          U+2029     Paragraph separator
         A "word" character is an underscore or any character less than 256 that
         is  a  letter  or  digit.  The definition of letters and digits is con-
-Line 2964 
 BACKSLASH
+Line 3021 
 BACKSLASH
         specific  matching is taking place (see "Locale support" in the pcreapi
         page). For example, in a French locale such  as  "fr_FR"  in  Unix-like
         systems,  or "french" in Windows, some character codes greater than 128
-        are used for accented letters, and these are matched by \w.
+        are used for accented letters, and these are matched by \w. The use  of
+        locales with Unicode is discouraged.
-        In UTF-8 mode, characters with values greater than 128 never match  \d,
-        \s, or \w, and always match \D, \S, and \W. This is true even when Uni-
-        code character property support is available. The use of  locales  with
-        Unicode is discouraged.
     Newline sequences
         Outside  a  character class, the escape sequence \R matches any Unicode
-        newline sequence. This is an extension to Perl. In non-UTF-8 mode \R is
+        newline sequence. This is a Perl 5.10 feature. In non-UTF-8 mode \R  is
         equivalent to the following:
           (?>\r\n|\n|\x0b|\f|\r|\x85)
-Line 2996 
 BACKSLASH
+Line 3049 
 BACKSLASH
     Unicode character properties
         When PCRE is built with Unicode character property support, three addi-
-        tional escape sequences to match  character  properties  are  available
+        tional escape sequences that match characters with specific  properties
-        when UTF-8 mode is selected. They are:
+        are  available.   When not in UTF-8 mode, these sequences are of course
+        limited to testing characters whose codepoints are less than  256,  but
+        they do work in this mode.  The extra escape sequences are:
           \p{xx}   a character with the xx property
           \P{xx}   a character without the xx property
-Line 3111 
 BACKSLASH
+Line 3166 
 BACKSLASH
         That is, it matches a character without the "mark"  property,  followed
         by  zero  or  more  characters with the "mark" property, and treats the
         sequence as an atomic group (see below).  Characters  with  the  "mark"
-        property are typically accents that affect the preceding character.
+        property  are  typically  accents  that affect the preceding character.
+        None of them have codepoints less than 256, so  in  non-UTF-8  mode  \X
+        matches any one character.
         Matching  characters  by Unicode property is not fast, because PCRE has
         to search a structure that contains  data  for  over  fifteen  thousand
-Line 3537 
 SUBPATTERNS
+Line 3594 
 SUBPATTERNS
         "Saturday".
+ DUPLICATE SUBPATTERN NUMBERS
+        Perl 5.10 introduced a feature whereby each alternative in a subpattern
+        uses the same numbers for its capturing parentheses. Such a  subpattern
+        starts  with (?| and is itself a non-capturing subpattern. For example,
+        consider this pattern:
+          (?|(Sat)ur|(Sun))day
+        Because the two alternatives are inside a (?| group, both sets of  cap-
+        turing  parentheses  are  numbered one. Thus, when the pattern matches,
+        you can look at captured substring number  one,  whichever  alternative
+        matched.  This  construct  is useful when you want to capture part, but
+        not all, of one of a number of alternatives. Inside a (?| group, paren-
+        theses  are  numbered as usual, but the number is reset at the start of
+        each branch. The numbers of any capturing buffers that follow the  sub-
+        pattern  start after the highest number used in any branch. The follow-
+        ing example is taken from the Perl documentation.  The  numbers  under-
+        neath show in which buffer the captured content will be stored.
+          # before  ---------------branch-reset----------- after
+          / ( a )  (?| x ( y ) z | (p (q) r) | (t) u (v) ) ( z ) /x
+          # 1            2         2  3        2     3     4
+        A  backreference  or  a  recursive call to a numbered subpattern always
+        refers to the first one in the pattern with the given number.
+        An alternative approach to using this "branch reset" feature is to  use
+        duplicate named subpatterns, as described in the next section.
  NAMED SUBPATTERNS
         Identifying  capturing  parentheses  by number is simple, but it can be
-Line 3576 
 NAMED SUBPATTERNS
+Line 3664 
 NAMED SUBPATTERNS
           (?<DN>Sat)(?:urday)?
         There  are  five capturing substrings, but only one is ever set after a
-        match.  The convenience  function  for  extracting  the  data  by  name
+        match.  (An alternative way of solving this problem is to use a "branch
-        returns  the  substring  for  the first (and in this example, the only)
+        reset" subpattern, as described in the previous section.)
-        subpattern of that name that matched.  This  saves  searching  to  find
-        which  numbered  subpattern  it  was. If you make a reference to a non-
+        The  convenience  function  for extracting the data by name returns the
-        unique named subpattern from elsewhere in the  pattern,  the  one  that
+        substring for the first (and in this example, the only)  subpattern  of
-        corresponds  to  the  lowest number is used. For further details of the
+        that  name  that  matched.  This saves searching to find which numbered
-        interfaces for handling named subpatterns, see the  pcreapi  documenta-
+        subpattern it was. If you make a reference to a non-unique  named  sub-
-        tion.
+        pattern  from elsewhere in the pattern, the one that corresponds to the
+        lowest number is used. For further details of the interfaces  for  han-
+        dling named subpatterns, see the pcreapi documentation.
  REPETITION
-Line 4455 
 AUTHOR
+Line 4545 
 AUTHOR
  REVISION
-        Last updated: 29 May 2007
+        Last updated: 19 June 2007
         Copyright (c) 1997-2007 University of Cambridge.
  ------------------------------------------------------------------------------
-Line 4786 
 RE-USING A PRECOMPILED PATTERN
+Line 4876 
 RE-USING A PRECOMPILED PATTERN
  COMPATIBILITY WITH DIFFERENT PCRE RELEASES
-        The layout of the control block that is at the start of the  data  that
+        In general, it is safest to  recompile  all  saved  patterns  when  you
-        makes  up  a  compiled pattern was changed for release 5.0. If you have
+        update  to  a new PCRE release, though not all updates actually require
-        any saved patterns that were compiled with  previous  releases  (not  a
+        this. Recompiling is definitely needed for release 7.2.
-        facility  that  was  previously advertised), you will have to recompile
-        them for release 5.0 and above.
-        If you have any saved patterns in UTF-8 mode that use  \p  or  \P  that
-        were  compiled  with any release up to and including 6.4, you will have
-        to recompile them for release 6.5 and above.
-        All saved patterns from earlier releases must be recompiled for release
-.0  or  higher,  because  there was an internal reorganization at that
-        release.
  AUTHOR
-Line 4810 
 AUTHOR
+Line 4890 
 AUTHOR
  REVISION
-        Last updated: 24 April 2007
+        Last updated: 13 June 2007
         Copyright (c) 1997-2007 University of Cambridge.
  ------------------------------------------------------------------------------
-Line 5545 
 PCRE SAMPLE PROGRAM
+Line 5625 
 PCRE SAMPLE PROGRAM
         bility  of  matching an empty string. Comments in the code explain what
         is going on.
-        If PCRE is installed in the standard include  and  library  directories
+        The demonstration program is automatically built if you use  "./config-
-        for  your  system, you should be able to compile the demonstration pro-
+        ure;make"  to  build PCRE. Otherwise, if PCRE is installed in the stan-
-        gram using this command:
+        dard include and library directories for your  system,  you  should  be
+        able to compile the demonstration program using this command:
           gcc -o pcredemo pcredemo.c -lpcre
-        If PCRE is installed elsewhere, you may need to add additional  options
+        If  PCRE is installed elsewhere, you may need to add additional options
-        to  the  command line. For example, on a Unix-like system that has PCRE
+        to the command line. For example, on a Unix-like system that  has  PCRE
-        installed in /usr/local, you  can  compile  the  demonstration  program
+        installed  in  /usr/local,  you  can  compile the demonstration program
         using a command like this:
           gcc -o pcredemo -I/usr/local/include pcredemo.c \
               -L/usr/local/lib -lpcre
-        Once  you  have  compiled the demonstration program, you can run simple
+        Once you have compiled the demonstration program, you  can  run  simple
         tests like this:
           ./pcredemo 'cat|dog' 'the cat sat on the mat'
           ./pcredemo -g 'cat|dog' 'the dog sat on the cat'
-        Note that there is a  much  more  comprehensive  test  program,  called
+        Note  that  there  is  a  much  more comprehensive test program, called
-        pcretest,  which  supports  many  more  facilities  for testing regular
+        pcretest, which supports  many  more  facilities  for  testing  regular
         expressions and the PCRE library. The pcredemo program is provided as a
         simple coding example.
-Line 5574 
 PCRE SAMPLE PROGRAM
+Line 5655 
 PCRE SAMPLE PROGRAM
         the standard library directory, you may get an error like this when you
         try to run pcredemo:
-          ld.so.1:  a.out:  fatal:  libpcre.so.0:  open failed: No such file or
+          ld.so.1: a.out: fatal: libpcre.so.0: open failed:  No  such  file  or
         directory
-        This is caused by the way shared library support works  on  those  sys-
+        This  is  caused  by the way shared library support works on those sys-
         tems. You need to add
           -R/usr/local/lib
-Line 5594 
 AUTHOR
+Line 5675 
 AUTHOR
  REVISION
-        Last updated: 06 March 2007
+        Last updated: 13 June 2007
         Copyright (c) 1997-2007 University of Cambridge.
  ------------------------------------------------------------------------------
  PCRESTACK(3)                                                      PCRESTACK(3)
-Line 5664 
 PCRE DISCUSSION OF STACK USAGE
+Line 5745 
 PCRE DISCUSSION OF STACK USAGE
         In environments where stack memory is constrained, you  might  want  to
         compile  PCRE to use heap memory instead of stack for remembering back-
         up points. This makes it run a lot more slowly, however. Details of how
-        to do this are given in the pcrebuild documentation.
+        to do this are given in the pcrebuild documentation. When built in this
+        way, instead of using the stack, PCRE obtains and frees memory by call-
-        In  Unix-like environments, there is not often a problem with the stack
+        ing  the  functions  that  are  pointed to by the pcre_stack_malloc and
-        unless very long strings are involved,  though  the  default  limit  on
+        pcre_stack_free variables. By default,  these  point  to  malloc()  and
-        stack  size  varies  from system to system. Values from 8Mb to 64Mb are
+        free(),  but you can replace the pointers to cause PCRE to use your own
+        functions. Since the block sizes are always the same,  and  are  always
+        freed in reverse order, it may be possible to implement customized mem-
+        ory handlers that are more efficient than the standard functions.
+        In Unix-like environments, there is not often a problem with the  stack
+        unless  very  long  strings  are  involved, though the default limit on
+        stack size varies from system to system. Values from 8Mb  to  64Mb  are
         common. You can find your default limit by running the command:
           ulimit -s
-        Unfortunately, the effect of running out of  stack  is  often  SIGSEGV,
+        Unfortunately,  the  effect  of  running out of stack is often SIGSEGV,
-        though  sometimes  a more explicit error message is given. You can nor-
+        though sometimes a more explicit error message is given. You  can  nor-
         mally increase the limit on stack size by code such as this:
           struct rlimit rlim;
-Line 5682 
 PCRE DISCUSSION OF STACK USAGE
+Line 5770 
 PCRE DISCUSSION OF STACK USAGE
           rlim.rlim_cur = 100*1024*1024;
           setrlimit(RLIMIT_STACK, &rlim);
-        This reads the current limits (soft and hard) using  getrlimit(),  then
+        This  reads  the current limits (soft and hard) using getrlimit(), then
-        attempts  to  increase  the  soft limit to 100Mb using setrlimit(). You
+        attempts to increase the soft limit to  100Mb  using  setrlimit().  You
         must do this before calling pcre_exec().
-        PCRE has an internal counter that can be used to  limit  the  depth  of
+        PCRE  has  an  internal  counter that can be used to limit the depth of
-        recursion,  and  thus cause pcre_exec() to give an error code before it
+        recursion, and thus cause pcre_exec() to give an error code  before  it
-        runs out of stack. By default, the limit is very  large,  and  unlikely
+        runs  out  of  stack. By default, the limit is very large, and unlikely
-        ever  to operate. It can be changed when PCRE is built, and it can also
+        ever to operate. It can be changed when PCRE is built, and it can  also
         be set when pcre_exec() is called. For details of these interfaces, see
         the pcrebuild and pcreapi documentation.
         As a very rough rule of thumb, you should reckon on about 500 bytes per
-        recursion. Thus, if you want to limit your  stack  usage  to  8Mb,  you
+        recursion.  Thus,  if  you  want  to limit your stack usage to 8Mb, you
-        should  set  the  limit at 16000 recursions. A 64Mb stack, on the other
+        should set the limit at 16000 recursions. A 64Mb stack,  on  the  other
-        hand, can support around 128000 recursions. The pcretest  test  program
+        hand,  can  support around 128000 recursions. The pcretest test program
         has a command line option (-S) that can be used to increase the size of
         its stack.
-Line 5710 
 AUTHOR
+Line 5798 
 AUTHOR
  REVISION
-        Last updated: 12 March 2007
+        Last updated: 05 June 2007
         Copyright (c) 1997-2007 University of Cambridge.
  ------------------------------------------------------------------------------

 Legend:



Removed from v.172
 


changed lines


 
Added in v.202
 Legend:



Removed from v.172
 


changed lines


 
Added in v.202
-Removed from v.172
+Added in v.202

webmaster@exim.org	ViewVC Help
Powered by ViewVC 1.1.12