pcre.3

Apache V2.0.15 Alpha For Linuxhttpd-2_0_15-alpha.tar.Z

memory failed for \fBpcre_get_substring()\fR.

  PCRE_ERROR_NOSUBSTRING    (-7)

There is no substring whose number is \fIstringnumber\fR.

The \fBpcre_get_substring_list()\fR function extracts all available substrings
and builds a list of pointers to them. All this is done in a single block of
memory which is obtained via \fBpcre_malloc\fR. The address of the memory block
is returned via \fIlistptr\fR, which is also the start of the list of string
pointers. The end of the list is marked by a NULL pointer. The yield of the
function is zero if all went well, or

  PCRE_ERROR_NOMEMORY       (-6)

if the attempt to get the memory block failed.

When any of these functions encounter a substring that is unset, which can
happen when capturing subpattern number \fIn+1\fR matches some part of the
subject, but subpattern \fIn\fR has not been used at all, they return an empty
string. This can be distinguished from a genuine zero-length substring by
inspecting the appropriate offset in \fIovector\fR, which is negative for unset
substrings.



.SH LIMITATIONS
There are some size limitations in PCRE but it is hoped that they will never in
practice be relevant.
The maximum length of a compiled pattern is 65539 (sic) bytes.
All values in repeating quantifiers must be less than 65536.
The maximum number of capturing subpatterns is 99.
The maximum number of all parenthesized subpatterns, including capturing
subpatterns, assertions, and other types of subpattern, is 200.

The maximum length of a subject string is the largest positive number that an
integer variable can hold. However, PCRE uses recursion to handle subpatterns
and indefinite repetition. This means that the available stack space may limit
the size of a subject string that can be processed by certain patterns.


.SH DIFFERENCES FROM PERL
The differences described here are with respect to Perl 5.005.

1. By default, a whitespace character is any character that the C library
function \fBisspace()\fR recognizes, though it is possible to compile PCRE with
alternative character type tables. Normally \fBisspace()\fR matches space,
formfeed, newline, carriage return, horizontal tab, and vertical tab. Perl 5
no longer includes vertical tab in its set of whitespace characters. The \\v
escape that was in the Perl documentation for a long time was never in fact
recognized. However, the character itself was treated as whitespace at least
up to 5.002. In 5.004 and 5.005 it does not match \\s.

2. PCRE does not allow repeat quantifiers on lookahead assertions. Perl permits
them, but they do not mean what you might think. For example, (?!a){3} does
not assert that the next three characters are not "a". It just asserts that the
next character is not "a" three times.

3. Capturing subpatterns that occur inside negative lookahead assertions are
counted, but their entries in the offsets vector are never set. Perl sets its
numerical variables from any such patterns that are matched before the
assertion fails to match something (thereby succeeding), but only if the
negative lookahead assertion contains just one branch.

4. Though binary zero characters are supported in the subject string, they are
not allowed in a pattern string because it is passed as a normal C string,
terminated by zero. The escape sequence "\\0" can be used in the pattern to
represent a binary zero.

5. The following Perl escape sequences are not supported: \\l, \\u, \\L, \\U,
\\E, \\Q. In fact these are implemented by Perl's general string-handling and
are not part of its pattern matching engine.

6. The Perl \\G assertion is not supported as it is not relevant to single
pattern matches.

7. Fairly obviously, PCRE does not support the (?{code}) and (?p{code})
constructions. However, there is some experimental support for recursive
patterns using the non-Perl item (?R).

8. There are at the time of writing some oddities in Perl 5.005_02 concerned
with the settings of captured strings when part of a pattern is repeated. For
example, matching "aba" against the pattern /^(a(b)?)+$/ sets $2 to the value
"b", but matching "aabbaa" against /^(aa(bb)?)+$/ leaves $2 unset. However, if
the pattern is changed to /^(aa(b(b))?)+$/ then $2 (and $3) are set.

In Perl 5.004 $2 is set in both cases, and that is also true of PCRE. If in the
future Perl changes to a consistent state that is different, PCRE may change to
follow.

9. Another as yet unresolved discrepancy is that in Perl 5.005_02 the pattern
/^(a)?(?(1)a|b)+$/ matches the string "a", whereas in PCRE it does not.
However, in both Perl and PCRE /^(a)?a/ matched against "a" leaves $1 unset.

10. PCRE provides some extensions to the Perl regular expression facilities:

(a) Although lookbehind assertions must match fixed length strings, each
alternative branch of a lookbehind assertion can match a different length of
string. Perl 5.005 requires them all to have the same length.

(b) If PCRE_DOLLAR_ENDONLY is set and PCRE_MULTILINE is not set, the $ 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 special
meaning is faulted.

(d) If PCRE_UNGREEDY is set, the greediness of the repetition quantifiers is
inverted, that is, by default they are not greedy, but if followed by a
question mark they are.

(e) PCRE_ANCHORED can be used to force a pattern to be tried only at the start
of the subject.

(f) The PCRE_NOTBOL, PCRE_NOTEOL, and PCRE_NOTEMPTY options for
\fBpcre_exec()\fR have no Perl equivalents.

(g) The (?R) construct allows for recursive pattern matching (Perl 5.6 can do
this using the (?p{code}) construct, which PCRE cannot of course support.)


.SH REGULAR EXPRESSION DETAILS
The syntax and semantics of the regular expressions supported by PCRE are
described below. Regular expressions are also described in the Perl
documentation and in a number of other books, some of which have copious
examples. Jeffrey Friedl's "Mastering Regular Expressions", published by
O'Reilly (ISBN 1-56592-257), covers them in great detail. The description
here is intended as reference documentation.

A regular expression is a pattern that is matched against a subject string from
left to right. Most characters stand for themselves in a pattern, and match the
corresponding characters in the subject. As a trivial example, the pattern

  The quick brown fox

matches a portion of a subject string that is identical to itself. The power of
regular expressions comes from the ability to include alternatives and
repetitions in the pattern. These are encoded in the pattern by the use of
\fImeta-characters\fR, which do not stand for themselves but instead are
interpreted in some special way.

There are two different sets of meta-characters: those that are recognized
anywhere in the pattern except within square brackets, and those that are
recognized in square brackets. Outside square brackets, the meta-characters are
as follows:

  \\      general escape character with several uses
  ^      assert start of subject (or line, in multiline mode)
  $      assert end of subject (or line, in multiline mode)
  .      match any character except newline (by default)
  [      start character class definition
  |      start of alternative branch
  (      start subpattern
  )      end subpattern
  ?      extends the meaning of (
         also 0 or 1 quantifier
         also quantifier minimizer
  *      0 or more quantifier
  +      1 or more quantifier
  {      start min/max quantifier

Part of a pattern that is in square brackets is called a "character class". In
a character class the only meta-characters are:

  \\      general escape character
  ^      negate the class, but only if the first character
  -      indicates character range
  ]      terminates the character class

The following sections describe the use of each of the meta-characters.


.SH BACKSLASH
The backslash character has several uses. Firstly, if it is followed by a
non-alphameric character, it takes away any special meaning that character may
have. This use of backslash as an escape character applies both inside and
outside character classes.

For example, if you want to match a "*" character, you write "\\*" in the
pattern. This applies whether or not the following character would otherwise be
interpreted as a meta-character, so it is always safe to precede a
non-alphameric with "\\" to specify that it stands for itself. In particular,
if you want to match a backslash, you write "\\\\".

If a pattern is compiled with the PCRE_EXTENDED option, whitespace in the
pattern (other than in a character class) and characters between a "#" outside
a character class and the next newline character are ignored. An escaping
backslash can be used to include a whitespace or "#" character as part of the
pattern.

A second use of backslash provides a way of encoding non-printing characters
in patterns in a visible manner. There is no restriction on the appearance of
non-printing characters, apart from the binary zero that terminates a pattern,
but when a pattern is being prepared by text editing, it is usually easier to
use one of the following escape sequences than the binary character it
represents:

  \\a     alarm, that is, the BEL character (hex 07)
  \\cx    "control-x", where x is any character
  \\e     escape (hex 1B)
  \\f     formfeed (hex 0C)
  \\n     newline (hex 0A)
  \\r     carriage return (hex 0D)
  \\t     tab (hex 09)
  \\xhh   character with hex code hh
  \\ddd   character with octal code ddd, or backreference

The precise effect of "\\cx" is as follows: if "x" is a lower case letter, it
is converted to upper case. Then bit 6 of the character (hex 40) is inverted.
Thus "\\cz" becomes hex 1A, but "\\c{" becomes hex 3B, while "\\c;" becomes hex
7B.

After "\\x", up to two hexadecimal digits are read (letters can be in upper or
lower case).

After "\\0" up to two further octal digits are read. In both cases, if there
are fewer than two digits, just those that are present are used. Thus the
sequence "\\0\\x\\07" specifies two binary zeros followed by a BEL character.
Make sure you supply two digits after the initial zero if the character that
follows is itself an octal digit.

The handling of a backslash followed by a digit other than 0 is complicated.
Outside a character class, PCRE reads it and any following digits as a decimal
number. If the number is less than 10, or if there have been at least that many
previous capturing left parentheses in the expression, the entire sequence is
taken as a \fIback reference\fR. A description of how this works is given
later, following the discussion of parenthesized subpatterns.

Inside a character class, or if the decimal number is greater than 9 and there
have not been that many capturing subpatterns, PCRE re-reads up to three octal
digits following the backslash, and generates a single byte from the least
significant 8 bits of the value. Any subsequent digits stand for themselves.
For example:

  \\040   is another way of writing a space
  \\40    is the same, provided there are fewer than 40
            previous capturing subpatterns
  \\7     is always a back reference
  \\11    might be a back reference, or another way of
            writing a tab
  \\011   is always a tab
  \\0113  is a tab followed by the character "3"
  \\113   is the character with octal code 113 (since there
            can be no more than 99 back references)
  \\377   is a byte consisting entirely of 1 bits
  \\81    is either a back reference, or a binary zero
            followed by the two characters "8" and "1"

Note that octal values of 100 or greater must not be introduced by a leading
zero, because no more than three octal digits are ever read.

All the sequences that define a single byte value can be used both inside and
outside character classes. In addition, inside a character class, the sequence
"\\b" is interpreted as the backspace character (hex 08). Outside a character
class it has a different meaning (see below).

The third use of backslash is for specifying generic character types:

  \\d     any decimal digit
  \\D     any character that is not a decimal digit
  \\s     any whitespace character
  \\S     any character that is not a whitespace character
  \\w     any "word" character
  \\W     any "non-word" character

Each pair of escape sequences partitions the complete set of characters into
two disjoint sets. Any given character matches one, and only one, of each pair.

A "word" character is any letter or digit or the underscore character, that is,
any character which can be part of a Perl "word". The definition of letters and
digits is controlled by PCRE's character tables, and may vary if locale-
specific matching is taking place (see "Locale support" above). For example, in
the "fr" (French) locale, some character codes greater than 128 are used for
accented letters, and these are matched by \\w.

These character type sequences can appear both inside and outside character
classes. They each match one character of the appropriate type. If the current
matching point is at the end of the subject string, all of them fail, since
there is no character to match.

The fourth use of backslash is for certain simple assertions. An assertion
specifies a condition that has to be met at a particular point in a match,
without consuming any characters from the subject string. The use of
subpatterns for more complicated assertions is described below. The backslashed
assertions are