pcre.3

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

.TH PCRE 3
.SH NAME
pcre - Perl-compatible regular expressions.
.SH SYNOPSIS
.B #include <pcre.h>
.PP
.SM
.br
.B pcre *pcre_compile(const char *\fIpattern\fR, int \fIoptions\fR,
.ti +5n
.B const char **\fIerrptr\fR, int *\fIerroffset\fR,
.ti +5n
.B const unsigned char *\fItableptr\fR);
.PP
.br
.B pcre_extra *pcre_study(const pcre *\fIcode\fR, int \fIoptions\fR,
.ti +5n
.B const char **\fIerrptr\fR);
.PP
.br
.B int pcre_exec(const pcre *\fIcode\fR, "const pcre_extra *\fIextra\fR,"
.ti +5n
.B "const char *\fIsubject\fR," int \fIlength\fR, int \fIstartoffset\fR,
.ti +5n
.B int \fIoptions\fR, int *\fIovector\fR, int \fIovecsize\fR);
.PP
.br
.B int pcre_copy_substring(const char *\fIsubject\fR, int *\fIovector\fR,
.ti +5n
.B int \fIstringcount\fR, int \fIstringnumber\fR, char *\fIbuffer\fR,
.ti +5n
.B int \fIbuffersize\fR);
.PP
.br
.B int pcre_get_substring(const char *\fIsubject\fR, int *\fIovector\fR,
.ti +5n
.B int \fIstringcount\fR, int \fIstringnumber\fR,
.ti +5n
.B const char **\fIstringptr\fR);
.PP
.br
.B int pcre_get_substring_list(const char *\fIsubject\fR,
.ti +5n
.B int *\fIovector\fR, int \fIstringcount\fR, "const char ***\fIlistptr\fR);"
.PP
.br
.B const unsigned char *pcre_maketables(void);
.PP
.br
.B int pcre_fullinfo(const pcre *\fIcode\fR, "const pcre_extra *\fIextra\fR,"
.ti +5n
.B int \fIwhat\fR, void *\fIwhere\fR);
.PP
.br
.B int pcre_info(const pcre *\fIcode\fR, int *\fIoptptr\fR, int
.B *\fIfirstcharptr\fR);
.PP
.br
.B char *pcre_version(void);
.PP
.br
.B void *(*pcre_malloc)(size_t);
.PP
.br
.B void (*pcre_free)(void *);



.SH DESCRIPTION
The PCRE library is a set of functions that implement regular expression
pattern matching using the same syntax and semantics as Perl 5, with just a few
differences (see below). The current implementation corresponds to Perl 5.005,
with some additional features from the Perl development release.

PCRE has its own native API, which is described in this document. There is also
a set of wrapper functions that correspond to the POSIX regular expression API.
These are described in the \fBpcreposix\fR documentation.

The native API function prototypes are defined in the header file \fBpcre.h\fR,
and on Unix systems the library itself is called \fBlibpcre.a\fR, so can be
accessed by adding \fB-lpcre\fR to the command for linking an application which
calls it. The header file defines the macros PCRE_MAJOR and PCRE_MINOR to
contain the major and minor release numbers for the library. Applications can
use these to include support for different releases.

The functions \fBpcre_compile()\fR, \fBpcre_study()\fR, and \fBpcre_exec()\fR
are used for compiling and matching regular expressions, while
\fBpcre_copy_substring()\fR, \fBpcre_get_substring()\fR, and
\fBpcre_get_substring_list()\fR are convenience functions for extracting
captured substrings from a matched subject string. The function
\fBpcre_maketables()\fR is used (optionally) to build a set of character tables
in the current locale for passing to \fBpcre_compile()\fR.

The function \fBpcre_fullinfo()\fR is used to find out information about a
compiled pattern; \fBpcre_info()\fR is an obsolete version which returns only
some of the available information, but is retained for backwards compatibility.
The function \fBpcre_version()\fR returns a pointer to a string containing the
version of PCRE and its date of release.

The global variables \fBpcre_malloc\fR and \fBpcre_free\fR initially contain
the entry points of the standard \fBmalloc()\fR and \fBfree()\fR functions
respectively. PCRE calls the memory management functions via these variables,
so a calling program can replace them if it wishes to intercept the calls. This
should be done before calling any PCRE functions.


.SH MULTI-THREADING
The PCRE functions can be used in multi-threading applications, with the
proviso that the memory management functions pointed to by \fBpcre_malloc\fR
and \fBpcre_free\fR are shared by all threads.

The compiled form of a regular expression is not altered during matching, so
the same compiled pattern can safely be used by several threads at once.


.SH COMPILING A PATTERN
The function \fBpcre_compile()\fR is called to compile a pattern into an
internal form. The pattern is a C string terminated by a binary zero, and
is passed in the argument \fIpattern\fR. A pointer to a single block of memory
that is obtained via \fBpcre_malloc\fR is returned. This contains the
compiled code and related data. The \fBpcre\fR type is defined for this for
convenience, but in fact \fBpcre\fR is just a typedef for \fBvoid\fR, since the
contents of the block are not externally defined. It is up to the caller to
free the memory when it is no longer required.
.PP
The size of a compiled pattern is roughly proportional to the length of the
pattern string, except that each character class (other than those containing
just a single character, negated or not) requires 33 bytes, and repeat
quantifiers with a minimum greater than one or a bounded maximum cause the
relevant portions of the compiled pattern to be replicated.
.PP
The \fIoptions\fR argument contains independent bits that affect the
compilation. It should be zero if no options are required. Some of the options,
in particular, those that are compatible with Perl, can also be set and unset
from within the pattern (see the detailed description of regular expressions
below). For these options, the contents of the \fIoptions\fR argument specifies
their initial settings at the start of compilation and execution. The
PCRE_ANCHORED option can be set at the time of matching as well as at compile
time.
.PP
If \fIerrptr\fR is NULL, \fBpcre_compile()\fR returns NULL immediately.
Otherwise, if compilation of a pattern fails, \fBpcre_compile()\fR returns
NULL, and sets the variable pointed to by \fIerrptr\fR to point to a textual
error message. The offset from the start of the pattern to the character where
the error was discovered is placed in the variable pointed to by
\fIerroffset\fR, which must not be NULL. If it is, an immediate error is given.
.PP
If the final argument, \fItableptr\fR, is NULL, PCRE uses a default set of
character tables which are built when it is compiled, using the default C
locale. Otherwise, \fItableptr\fR must be the result of a call to
\fBpcre_maketables()\fR. See the section on locale support below.
.PP
The following option bits are defined in the header file:

  PCRE_ANCHORED

If this bit is set, the pattern is forced to be "anchored", that is, it is
constrained to match only at the start of the string which is being searched
(the "subject string"). This effect can also be achieved by appropriate
constructs in the pattern itself, which is the only way to do it in Perl.

  PCRE_CASELESS

If this bit is set, letters in the pattern match both upper and lower case
letters. It is equivalent to Perl's /i option.

  PCRE_DOLLAR_ENDONLY

If this bit is set, a dollar metacharacter in the pattern matches only at the
end of the subject string. Without this option, a dollar also matches
immediately before the final character if it is a newline (but not before any
other newlines). The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is
set. There is no equivalent to this option in Perl.

  PCRE_DOTALL

If this bit is set, a dot metacharater in the pattern matches all characters,
including newlines. Without it, newlines are excluded. This option is
equivalent to Perl's /s option. A negative class such as [^a] always matches a
newline character, independent of the setting of this option.

  PCRE_EXTENDED

If this bit is set, whitespace data characters in the pattern are totally
ignored except when escaped or inside a character class, and characters between
an unescaped # outside a character class and the next newline character,
inclusive, are also ignored. This is equivalent to Perl's /x option, and makes
it possible to include comments inside complicated patterns. Note, however,
that this applies only to data characters. Whitespace characters may never
appear within special character sequences in a pattern, for example within the
sequence (?( which introduces a conditional subpattern.

  PCRE_EXTRA

This option was invented in order to turn on additional functionality of PCRE
that is incompatible with Perl, but it is currently of very little use. When
set, any backslash in a pattern that is followed by a letter that has no
special meaning causes an error, thus reserving these combinations for future
expansion. By default, as in Perl, a backslash followed by a letter with no
special meaning is treated as a literal. There are at present no other features
controlled by this option. It can also be set by a (?X) option setting within a
pattern.

  PCRE_MULTILINE

By default, PCRE treats the subject string as consisting of a single "line" of
characters (even if it actually contains several newlines). The "start of line"
metacharacter (^) matches only at the start of the string, while the "end of
line" metacharacter ($) matches only at the end of the string, or before a
terminating newline (unless PCRE_DOLLAR_ENDONLY is set). This is the same as
Perl.

When PCRE_MULTILINE it is set, the "start of line" and "end of line" constructs
match immediately following or immediately before any newline in the subject
string, respectively, as well as at the very start and end. This is equivalent
to Perl's /m option. If there are no "\\n" characters in a subject string, or
no occurrences of ^ or $ in a pattern, setting PCRE_MULTILINE has no
effect.

  PCRE_UNGREEDY

This option inverts the "greediness" of the quantifiers so that they are not
greedy by default, but become greedy if followed by "?". It is not compatible
with Perl. It can also be set by a (?U) option setting within the pattern.


.SH STUDYING A PATTERN
When a pattern is going to be used several times, it is worth spending more
time analyzing it in order to speed up the time taken for matching. The
function \fBpcre_study()\fR takes a pointer to a compiled pattern as its first
argument, and returns a pointer to a \fBpcre_extra\fR block (another \fBvoid\fR
typedef) containing additional information about the pattern; this can be
passed to \fBpcre_exec()\fR. If no additional information is available, NULL
is returned.

The second argument contains option bits. At present, no options are defined
for \fBpcre_study()\fR, and this argument should always be zero.

The third argument for \fBpcre_study()\fR is a pointer to an error message. If
studying succeeds (even if no data is returned), the variable it points to is
set to NULL. Otherwise it points to a textual error message.

At present, studying a pattern is useful only for non-anchored patterns that do
not have a single fixed starting character. A bitmap of possible starting
characters is created.


.SH LOCALE SUPPORT
PCRE handles caseless matching, and determines whether characters are letters,
digits, or whatever, by reference to a set of tables. The library contains a
default set of tables which is created in the default C locale when PCRE is
compiled. This is used when the final argument of \fBpcre_compile()\fR is NULL,
and is sufficient for many applications.

An alternative set of tables can, however, be supplied. Such tables are built
by calling the \fBpcre_maketables()\fR function, which has no arguments, in the
relevant locale. The result can then be passed to \fBpcre_compile()\fR as often
as necessary. For example, to build and use tables that are appropriate for the
French locale (where accented characters with codes greater than 128 are
treated as letters), the following code could be used:

  setlocale(LC_CTYPE, "fr");
  tables = pcre_maketables();
  re = pcre_compile(..., tables);

The tables are built in memory that is obtained via \fBpcre_malloc\fR. The
pointer that is passed to \fBpcre_compile\fR is saved with the compiled
pattern, and the same tables are used via this pointer by \fBpcre_study()\fR
and \fBpcre_exec()\fR. Thus for any single pattern, compilation, studying and
matching all happen in the same locale, but different patterns can be compiled
in different locales. It is the caller's responsibility to ensure that the
memory containing the tables remains available for as long as it is needed.


.SH INFORMATION ABOUT A PATTERN
The \fBpcre_fullinfo()\fR function returns information about a compiled
pattern. It replaces the obsolete \fBpcre_info()\fR function, which is
nevertheless retained for backwards compability (and is documented below).

The first argument for \fBpcre_fullinfo()\fR is a pointer to the compiled
pattern. The second argument is the result of \fBpcre_study()\fR, or NULL if
the pattern was not studied. The third argument specifies which piece of
information is required, while the fourth argument is a pointer to a variable
to receive the data. The yield of the function is zero for success, or one of