.TH PCREAPI 3

.SH NAME

PCRE - Perl-compatible regular expressions

.SH "PCRE NATIVE API"

.rs

.sp

.B #include <pcre.h>

.PP

.SM

.B pcre *pcre_compile(const char *\fIpattern\fP, int \fIoptions\fP,

.ti +5n

.B const char **\fIerrptr\fP, int *\fIerroffset\fP,

.ti +5n

.B const unsigned char *\fItableptr\fP);

.PP

.B pcre *pcre_compile2(const char *\fIpattern\fP, int \fIoptions\fP,

.ti +5n

.B int *\fIerrorcodeptr\fP,

.ti +5n

.B const char **\fIerrptr\fP, int *\fIerroffset\fP,

.ti +5n

.B const unsigned char *\fItableptr\fP);

.PP

.B pcre_extra *pcre_study(const pcre *\fIcode\fP, int \fIoptions\fP,

.ti +5n

.B const char **\fIerrptr\fP);

.PP

.B int pcre_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP,"

.ti +5n

.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP,

.ti +5n

.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP);

.PP

.B int pcre_dfa_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP,"

.ti +5n

.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP,

.ti +5n

.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP,

.ti +5n

.B int *\fIworkspace\fP, int \fIwscount\fP);

.PP

.B int pcre_copy_named_substring(const pcre *\fIcode\fP,

.ti +5n

.B const char *\fIsubject\fP, int *\fIovector\fP,

.ti +5n

.B int \fIstringcount\fP, const char *\fIstringname\fP,

.ti +5n

.B char *\fIbuffer\fP, int \fIbuffersize\fP);

.PP

.B int pcre_copy_substring(const char *\fIsubject\fP, int *\fIovector\fP,

.ti +5n

.B int \fIstringcount\fP, int \fIstringnumber\fP, char *\fIbuffer\fP,

.ti +5n

.B int \fIbuffersize\fP);

.PP

.B int pcre_get_named_substring(const pcre *\fIcode\fP,

.ti +5n

.B const char *\fIsubject\fP, int *\fIovector\fP,

.ti +5n

.B int \fIstringcount\fP, const char *\fIstringname\fP,

.ti +5n

.B const char **\fIstringptr\fP);

.PP

.B int pcre_get_stringnumber(const pcre *\fIcode\fP,

.ti +5n

.B const char *\fIname\fP);

.PP

.B int pcre_get_stringtable_entries(const pcre *\fIcode\fP,

.ti +5n

.B const char *\fIname\fP, char **\fIfirst\fP, char **\fIlast\fP);

.PP

.B int pcre_get_substring(const char *\fIsubject\fP, int *\fIovector\fP,

.ti +5n

.B int \fIstringcount\fP, int \fIstringnumber\fP,

.ti +5n

.B const char **\fIstringptr\fP);

.PP

.B int pcre_get_substring_list(const char *\fIsubject\fP,

.ti +5n

.B int *\fIovector\fP, int \fIstringcount\fP, "const char ***\fIlistptr\fP);"

.PP

.B void pcre_free_substring(const char *\fIstringptr\fP);

.PP

.B void pcre_free_substring_list(const char **\fIstringptr\fP);

.PP

.B const unsigned char *pcre_maketables(void);

.PP

.B int pcre_fullinfo(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP,"

.ti +5n

.B int \fIwhat\fP, void *\fIwhere\fP);

.PP

.B int pcre_info(const pcre *\fIcode\fP, int *\fIoptptr\fP, int

.B *\fIfirstcharptr\fP);

.PP

.B int pcre_refcount(pcre *\fIcode\fP, int \fIadjust\fP);

.PP

.B int pcre_config(int \fIwhat\fP, void *\fIwhere\fP);

.PP

.B char *pcre_version(void);

.PP

.B void *(*pcre_malloc)(size_t);

.PP

.B void (*pcre_free)(void *);

.PP

.B void *(*pcre_stack_malloc)(size_t);

.PP

.B void (*pcre_stack_free)(void *);

.PP

.B int (*pcre_callout)(pcre_callout_block *);

.

.

.SH "PCRE API OVERVIEW"

.rs

.sp

PCRE has its own native API, which is described in this document. There are

also some wrapper functions that correspond to the POSIX regular expression

API. These are described in the

.\" HREF

\fBpcreposix\fP

.\"

documentation. Both of these APIs define a set of C function calls. A C++

wrapper is distributed with PCRE. It is documented in the

.\" HREF

\fBpcrecpp\fP

.\"

page.

.P

The native API C function prototypes are defined in the header file

\fBpcre.h\fP, and on Unix systems the library itself is called \fBlibpcre\fP.

It can normally be accessed by adding \fB-lpcre\fP to the command for linking

an application that uses PCRE. 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 of PCRE.

.P

The functions \fBpcre_compile()\fP, \fBpcre_compile2()\fP, \fBpcre_study()\fP,

and \fBpcre_exec()\fP are used for compiling and matching regular expressions

in a Perl-compatible manner. A sample program that demonstrates the simplest

way of using them is provided in the file called \fIpcredemo.c\fP in the source

distribution. The

.\" HREF

\fBpcresample\fP

.\"

documentation describes how to compile and run it.

.P

A second matching function, \fBpcre_dfa_exec()\fP, which is not

Perl-compatible, is also provided. This uses a different algorithm for the

matching. The alternative algorithm finds all possible matches (at a given

point in the subject), and scans the subject just once. However, this algorithm

does not return captured substrings. A description of the two matching

algorithms and their advantages and disadvantages is given in the

.\" HREF

\fBpcrematching\fP

.\"

documentation.

.P

In addition to the main compiling and matching functions, there are convenience

functions for extracting captured substrings from a subject string that is

matched by \fBpcre_exec()\fP. They are:

.sp

  \fBpcre_copy_substring()\fP

  \fBpcre_copy_named_substring()\fP

  \fBpcre_get_substring()\fP

  \fBpcre_get_named_substring()\fP

  \fBpcre_get_substring_list()\fP

  \fBpcre_get_stringnumber()\fP

  \fBpcre_get_stringtable_entries()\fP

.sp

\fBpcre_free_substring()\fP and \fBpcre_free_substring_list()\fP are also

provided, to free the memory used for extracted strings.

.P

The function \fBpcre_maketables()\fP is used to build a set of character tables

in the current locale for passing to \fBpcre_compile()\fP, \fBpcre_exec()\fP,

or \fBpcre_dfa_exec()\fP. This is an optional facility that is provided for

specialist use. Most commonly, no special tables are passed, in which case

internal tables that are generated when PCRE is built are used.

.P

The function \fBpcre_fullinfo()\fP is used to find out information about a

compiled pattern; \fBpcre_info()\fP is an obsolete version that returns only

some of the available information, but is retained for backwards compatibility.

The function \fBpcre_version()\fP returns a pointer to a string containing the

version of PCRE and its date of release.

.P

The function \fBpcre_refcount()\fP maintains a reference count in a data block

containing a compiled pattern. This is provided for the benefit of

object-oriented applications.

.P

The global variables \fBpcre_malloc\fP and \fBpcre_free\fP initially contain

the entry points of the standard \fBmalloc()\fP and \fBfree()\fP 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.

.P

The global variables \fBpcre_stack_malloc\fP and \fBpcre_stack_free\fP are also

indirections to memory management functions. These special functions are used

only when PCRE is compiled to use the heap for remembering data, instead of

recursive function calls, when running the \fBpcre_exec()\fP function. See the

.\" HREF

\fBpcrebuild\fP

.\"

documentation for details of how to do this. It is a non-standard way of

building PCRE, for use in environments that have limited stacks. Because of the

greater use of memory management, it runs more slowly. Separate functions are

provided so that special-purpose external code can be used for this case. When

used, these functions are always called in a stack-like manner (last obtained,

first freed), and always for memory blocks of the same size. There is a

discussion about PCRE's stack usage in the

.\" HREF

\fBpcrestack\fP

.\"

documentation.

.P

The global variable \fBpcre_callout\fP initially contains NULL. It can be set

by the caller to a "callout" function, which PCRE will then call at specified

points during a matching operation. Details are given in the

.\" HREF

\fBpcrecallout\fP

.\"

documentation.

.

.

.\" HTML <a name="newlines"></a>

.SH NEWLINES

.rs

.sp

PCRE supports five different conventions for indicating line breaks in

strings: a single CR (carriage return) character, a single LF (linefeed)

character, the two-character sequence CRLF, any of the three preceding, or any

Unicode newline sequence. The Unicode newline sequences are the three just

mentioned, plus the single characters VT (vertical tab, U+000B), FF (formfeed,

U+000C), NEL (next line, U+0085), LS (line separator, U+2028), and PS

(paragraph separator, U+2029).

.P

Each of the first three conventions is used by at least one operating system as

its standard newline sequence. When PCRE is built, a default can be specified.

The default default is LF, which is the Unix standard. When PCRE is run, the

default can be overridden, either when a pattern is compiled, or when it is

matched.

.P

At compile time, the newline convention can be specified by the \fIoptions\fP

argument of \fBpcre_compile()\fP, or it can be specified by special text at the

start of the pattern itself; this overrides any other settings. See the

.\" HREF

\fBpcrepattern\fP

.\"

page for details of the special character sequences.

.P

In the PCRE documentation the word "newline" is used to mean "the character or

pair of characters that indicate a line break". The choice of newline

convention affects the handling of the dot, circumflex, and dollar

metacharacters, the handling of #-comments in /x mode, and, when CRLF is a

recognized line ending sequence, the match position advancement for a

non-anchored pattern. There is more detail about this in the

.\" HTML <a href="#execoptions">

.\" </a>

section on \fBpcre_exec()\fP options

.\"

below.

.P

The choice of newline convention does not affect the interpretation of

the \en or \er escape sequences, nor does it affect what \eR matches, which is

controlled in a similar way, but by separate options.

.

.

.SH MULTITHREADING

.rs

.sp

The PCRE functions can be used in multi-threading applications, with the

proviso that the memory management functions pointed to by \fBpcre_malloc\fP,

\fBpcre_free\fP, \fBpcre_stack_malloc\fP, and \fBpcre_stack_free\fP, and the

callout function pointed to by \fBpcre_callout\fP, are shared by all threads.

.P

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 "SAVING PRECOMPILED PATTERNS FOR LATER USE"

.rs

.sp

The compiled form of a regular expression can be saved and re-used at a later

time, possibly by a different program, and even on a host other than the one on

which it was compiled. Details are given in the

.\" HREF

\fBpcreprecompile\fP

.\"

documentation. However, compiling a regular expression with one version of PCRE

for use with a different version is not guaranteed to work and may cause

crashes.

.

.

.SH "CHECKING BUILD-TIME OPTIONS"

.rs

.sp

.B int pcre_config(int \fIwhat\fP, void *\fIwhere\fP);

.PP

The function \fBpcre_config()\fP makes it possible for a PCRE client to

discover which optional features have been compiled into the PCRE library. The

.\" HREF

\fBpcrebuild\fP

.\"

documentation has more details about these optional features.

.P

The first argument for \fBpcre_config()\fP is an integer, specifying which

information is required; the second argument is a pointer to a variable into

which the information is placed. The following information is available:

.sp

  PCRE_CONFIG_UTF8

.sp

The output is an integer that is set to one if UTF-8 support is available;

otherwise it is set to zero.

.sp

  PCRE_CONFIG_UNICODE_PROPERTIES

.sp

The output is an integer that is set to one if support for Unicode character

properties is available; otherwise it is set to zero.

.sp

  PCRE_CONFIG_NEWLINE

.sp

The output is an integer whose value specifies the default character sequence

that is recognized as meaning "newline". The four values that are supported

are: 10 for LF, 13 for CR, 3338 for CRLF, -2 for ANYCRLF, and -1 for ANY. The

default should normally be the standard sequence for your operating system.

.sp

  PCRE_CONFIG_BSR

.sp

The output is an integer whose value indicates what character sequences the \eR

escape sequence matches by default. A value of 0 means that \eR matches any

Unicode line ending sequence; a value of 1 means that \eR matches only CR, LF,

or CRLF. The default can be overridden when a pattern is compiled or matched.

.sp

  PCRE_CONFIG_LINK_SIZE

.sp

The output is an integer that contains the number of bytes used for internal

linkage in compiled regular expressions. The value is 2, 3, or 4. Larger values

allow larger regular expressions to be compiled, at the expense of slower

matching. The default value of 2 is sufficient for all but the most massive

patterns, since it allows the compiled pattern to be up to 64K in size.

.sp

  PCRE_CONFIG_POSIX_MALLOC_THRESHOLD

.sp

The output is an integer that contains the threshold above which the POSIX

interface uses \fBmalloc()\fP for output vectors. Further details are given in

the

.\" HREF

\fBpcreposix\fP

.\"

documentation.

.sp

  PCRE_CONFIG_MATCH_LIMIT

.sp

The output is an integer that gives the default limit for the number of

internal matching function calls in a \fBpcre_exec()\fP execution. Further

details are given with \fBpcre_exec()\fP below.

.sp

  PCRE_CONFIG_MATCH_LIMIT_RECURSION

.sp

The output is an integer that gives the default limit for the depth of

recursion when calling the internal matching function in a \fBpcre_exec()\fP

execution. Further details are given with \fBpcre_exec()\fP below.

.sp

  PCRE_CONFIG_STACKRECURSE

.sp

The output is an integer that is set to one if internal recursion when running

\fBpcre_exec()\fP is implemented by recursive function calls that use the stack

to remember their state. This is the usual way that PCRE is compiled. The

output is zero if PCRE was compiled to use blocks of data on the heap instead

of recursive function calls. In this case, \fBpcre_stack_malloc\fP and

\fBpcre_stack_free\fP are called to manage memory blocks on the heap, thus

avoiding the use of the stack.

.

.

.SH "COMPILING A PATTERN"

.rs

.sp

.B pcre *pcre_compile(const char *\fIpattern\fP, int \fIoptions\fP,

.ti +5n

.B const char **\fIerrptr\fP, int *\fIerroffset\fP,

.ti +5n

.B const unsigned char *\fItableptr\fP);

.sp

.B pcre *pcre_compile2(const char *\fIpattern\fP, int \fIoptions\fP,

.ti +5n

.B int *\fIerrorcodeptr\fP,

.ti +5n

.B const char **\fIerrptr\fP, int *\fIerroffset\fP,

.ti +5n

.B const unsigned char *\fItableptr\fP);

.P

Either of the functions \fBpcre_compile()\fP or \fBpcre_compile2()\fP can be

called to compile a pattern into an internal form. The only difference between

the two interfaces is that \fBpcre_compile2()\fP has an additional argument,

\fIerrorcodeptr\fP, via which a numerical error code can be returned.

.P

The pattern is a C string terminated by a binary zero, and is passed in the

\fIpattern\fP argument. A pointer to a single block of memory that is obtained

via \fBpcre_malloc\fP is returned. This contains the compiled code and related

data. The \fBpcre\fP type is defined for the returned block; this is a typedef

for a structure whose contents are not externally defined. It is up to the

caller to free the memory (via \fBpcre_free\fP) when it is no longer required.

.P

Although the compiled code of a PCRE regex is relocatable, that is, it does not

depend on memory location, the complete \fBpcre\fP data block is not

fully relocatable, because it may contain a copy of the \fItableptr\fP

argument, which is an address (see below).

.P

The \fIoptions\fP argument contains various bit settings that affect the

compilation. It should be zero if no options are required. The available

options are described below. Some of them, in particular, those that are

compatible with Perl, can also be set and unset from within the pattern (see

the detailed description in the

.\" HREF

\fBpcrepattern\fP

.\"

documentation). For these options, the contents of the \fIoptions\fP argument

specifies their initial settings at the start of compilation and execution. The

PCRE_ANCHORED and PCRE_NEWLINE_\fIxxx\fP options can be set at the time of

matching as well as at compile time.

.P

If \fIerrptr\fP is NULL, \fBpcre_compile()\fP returns NULL immediately.

Otherwise, if compilation of a pattern fails, \fBpcre_compile()\fP returns

NULL, and sets the variable pointed to by \fIerrptr\fP to point to a textual

error message. This is a static string that is part of the library. You must

not try to free it. 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\fP, which must not be NULL. If it is, an immediate error is given.

.P

If \fBpcre_compile2()\fP is used instead of \fBpcre_compile()\fP, and the

\fIerrorcodeptr\fP argument is not NULL, a non-zero error code number is

returned via this argument in the event of an error. This is in addition to the

textual error message. Error codes and messages are listed below.

.P

If the final argument, \fItableptr\fP, is NULL, PCRE uses a default set of

character tables that are built when PCRE is compiled, using the default C

locale. Otherwise, \fItableptr\fP must be an address that is the result of a

call to \fBpcre_maketables()\fP. This value is stored with the compiled

pattern, and used again by \fBpcre_exec()\fP, unless another table pointer is

passed to it. For more discussion, see the section on locale support below.

.P

This code fragment shows a typical straightforward call to \fBpcre_compile()\fP:

.sp

  pcre *re;

  const char *error;

  int erroffset;

  re = pcre_compile(

    "^A.*Z",          /* the pattern */

    0,                /* default options */

    &error,           /* for error message */

    &erroffset,       /* for error offset */

    NULL);            /* use default character tables */

.sp

The following names for option bits are defined in the \fBpcre.h\fP header

file:

.sp

  PCRE_ANCHORED

.sp

If this bit is set, the pattern is forced to be "anchored", that is, it is

constrained to match only at the first matching point in the string that 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.

.sp

  PCRE_AUTO_CALLOUT

.sp

If this bit is set, \fBpcre_compile()\fP automatically inserts callout items,

all with number 255, before each pattern item. For discussion of the callout

facility, see the

.\" HREF

\fBpcrecallout\fP

.\"

documentation.

.sp

  PCRE_BSR_ANYCRLF

  PCRE_BSR_UNICODE

.sp

These options (which are mutually exclusive) control what the \eR escape

sequence matches. The choice is either to match only CR, LF, or CRLF, or to

match any Unicode newline sequence. The default is specified when PCRE is

built. It can be overridden from within the pattern, or by setting an option

when a compiled pattern is matched.

.sp

  PCRE_CASELESS

.sp

If this bit is set, letters in the pattern match both upper and lower case

letters. It is equivalent to Perl's /i option, and it can be changed within a

pattern by a (?i) option setting. In UTF-8 mode, PCRE always understands the

concept of case for characters whose values are less than 128, so caseless

matching is always possible. For characters with higher values, the concept of

case is supported if PCRE is compiled with Unicode property support, but not

otherwise. If you want to use caseless matching for characters 128 and above,

you must ensure that PCRE is compiled with Unicode property support as well as

with UTF-8 support.

.sp

  PCRE_DOLLAR_ENDONLY

.sp

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 a newline at the end of the string (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, and no way to set it within a

pattern.

.sp

  PCRE_DOTALL

.sp

If this bit is set, a dot metacharater in the pattern matches all characters,

including those that indicate newline. Without it, a dot does not match when

the current position is at a newline. This option is equivalent to Perl's /s

option, and it can be changed within a pattern by a (?s) option setting. A

negative class such as [^a] always matches newline characters, independent of

the setting of this option.

.sp

  PCRE_DUPNAMES

.sp

If this bit is set, names used to identify capturing subpatterns need not be

unique. This can be helpful for certain types of pattern when it is known that

only one instance of the named subpattern can ever be matched. There are more

details of named subpatterns below; see also the

.\" HREF

\fBpcrepattern\fP

.\"

documentation.

.sp

  PCRE_EXTENDED

.sp

If this bit is set, whitespace data characters in the pattern are totally

ignored except when escaped or inside a character class. Whitespace does not

include the VT character (code 11). In addition, characters between an

unescaped # outside a character class and the next newline, inclusive, are also

ignored. This is equivalent to Perl's /x option, and it can be changed within a

pattern by a (?x) option setting.