diff options
Diffstat (limited to 'srclib/pcre/doc/html/pcreapi.html')
| -rw-r--r-- | srclib/pcre/doc/html/pcreapi.html | 1287 |
1 files changed, 1287 insertions, 0 deletions
diff --git a/srclib/pcre/doc/html/pcreapi.html b/srclib/pcre/doc/html/pcreapi.html new file mode 100644 index 0000000000..72639f4cc3 --- /dev/null +++ b/srclib/pcre/doc/html/pcreapi.html @@ -0,0 +1,1287 @@ +<html> +<head> +<title>pcreapi specification</title> +</head> +<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB"> +<h1>pcreapi man page</h1> +<p> +Return to the <a href="index.html">PCRE index page</a>. +</p> +<p> +This page is part of the PCRE HTML documentation. It was generated automatically +from the original man page. If there is any nonsense in it, please consult the +man page, in case the conversion went wrong. +<br> +<ul> +<li><a name="TOC1" href="#SEC1">PCRE NATIVE API</a> +<li><a name="TOC2" href="#SEC2">PCRE API OVERVIEW</a> +<li><a name="TOC3" href="#SEC3">MULTITHREADING</a> +<li><a name="TOC4" href="#SEC4">SAVING PRECOMPILED PATTERNS FOR LATER USE</a> +<li><a name="TOC5" href="#SEC5">CHECKING BUILD-TIME OPTIONS</a> +<li><a name="TOC6" href="#SEC6">COMPILING A PATTERN</a> +<li><a name="TOC7" href="#SEC7">STUDYING A PATTERN</a> +<li><a name="TOC8" href="#SEC8">LOCALE SUPPORT</a> +<li><a name="TOC9" href="#SEC9">INFORMATION ABOUT A PATTERN</a> +<li><a name="TOC10" href="#SEC10">OBSOLETE INFO FUNCTION</a> +<li><a name="TOC11" href="#SEC11">MATCHING A PATTERN</a> +<li><a name="TOC12" href="#SEC12">EXTRACTING CAPTURED SUBSTRINGS BY NUMBER</a> +<li><a name="TOC13" href="#SEC13">EXTRACTING CAPTURED SUBSTRINGS BY NAME</a> +</ul> +<br><a name="SEC1" href="#TOC1">PCRE NATIVE API</a><br> +<P> +<b>#include <pcre.h></b> +</P> +<P> +<b>pcre *pcre_compile(const char *<i>pattern</i>, int <i>options</i>,</b> +<b>const char **<i>errptr</i>, int *<i>erroffset</i>,</b> +<b>const unsigned char *<i>tableptr</i>);</b> +</P> +<P> +<b>pcre_extra *pcre_study(const pcre *<i>code</i>, int <i>options</i>,</b> +<b>const char **<i>errptr</i>);</b> +</P> +<P> +<b>int pcre_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> +<b>const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b> +<b>int <i>options</i>, int *<i>ovector</i>, int <i>ovecsize</i>);</b> +</P> +<P> +<b>int pcre_copy_named_substring(const pcre *<i>code</i>,</b> +<b>const char *<i>subject</i>, int *<i>ovector</i>,</b> +<b>int <i>stringcount</i>, const char *<i>stringname</i>,</b> +<b>char *<i>buffer</i>, int <i>buffersize</i>);</b> +</P> +<P> +<b>int pcre_copy_substring(const char *<i>subject</i>, int *<i>ovector</i>,</b> +<b>int <i>stringcount</i>, int <i>stringnumber</i>, char *<i>buffer</i>,</b> +<b>int <i>buffersize</i>);</b> +</P> +<P> +<b>int pcre_get_named_substring(const pcre *<i>code</i>,</b> +<b>const char *<i>subject</i>, int *<i>ovector</i>,</b> +<b>int <i>stringcount</i>, const char *<i>stringname</i>,</b> +<b>const char **<i>stringptr</i>);</b> +</P> +<P> +<b>int pcre_get_stringnumber(const pcre *<i>code</i>,</b> +<b>const char *<i>name</i>);</b> +</P> +<P> +<b>int pcre_get_substring(const char *<i>subject</i>, int *<i>ovector</i>,</b> +<b>int <i>stringcount</i>, int <i>stringnumber</i>,</b> +<b>const char **<i>stringptr</i>);</b> +</P> +<P> +<b>int pcre_get_substring_list(const char *<i>subject</i>,</b> +<b>int *<i>ovector</i>, int <i>stringcount</i>, const char ***<i>listptr</i>);</b> +</P> +<P> +<b>void pcre_free_substring(const char *<i>stringptr</i>);</b> +</P> +<P> +<b>void pcre_free_substring_list(const char **<i>stringptr</i>);</b> +</P> +<P> +<b>const unsigned char *pcre_maketables(void);</b> +</P> +<P> +<b>int pcre_fullinfo(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> +<b>int <i>what</i>, void *<i>where</i>);</b> +</P> +<P> +<b>int pcre_info(const pcre *<i>code</i>, int *<i>optptr</i>, int</b> +<b>*<i>firstcharptr</i>);</b> +</P> +<P> +<b>int pcre_config(int <i>what</i>, void *<i>where</i>);</b> +</P> +<P> +<b>char *pcre_version(void);</b> +</P> +<P> +<b>void *(*pcre_malloc)(size_t);</b> +</P> +<P> +<b>void (*pcre_free)(void *);</b> +</P> +<P> +<b>void *(*pcre_stack_malloc)(size_t);</b> +</P> +<P> +<b>void (*pcre_stack_free)(void *);</b> +</P> +<P> +<b>int (*pcre_callout)(pcre_callout_block *);</b> +</P> +<br><a name="SEC2" href="#TOC1">PCRE API OVERVIEW</a><br> +<P> +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 +<a href="pcreposix.html"><b>pcreposix</b></a> +documentation. +</P> +<P> +The native API function prototypes are defined in the header file <b>pcre.h</b>, +and on Unix systems the library itself is called <b>libpcre</b>. It can +normally be accessed by adding <b>-lpcre</b> 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> +<P> +The functions <b>pcre_compile()</b>, <b>pcre_study()</b>, and <b>pcre_exec()</b> +are used for compiling and matching regular expressions. A sample program that +demonstrates the simplest way of using them is provided in the file called +<i>pcredemo.c</i> in the source distribution. The +<a href="pcresample.html"><b>pcresample</b></a> +documentation describes how to run it. +</P> +<P> +In addition to the main compiling and matching functions, there are convenience +functions for extracting captured substrings from a matched subject string. +They are: +<pre> + <b>pcre_copy_substring()</b> + <b>pcre_copy_named_substring()</b> + <b>pcre_get_substring()</b> + <b>pcre_get_named_substring()</b> + <b>pcre_get_substring_list()</b> + <b>pcre_get_stringnumber()</b> +</pre> +<b>pcre_free_substring()</b> and <b>pcre_free_substring_list()</b> are also +provided, to free the memory used for extracted strings. +</P> +<P> +The function <b>pcre_maketables()</b> is used to build a set of character tables +in the current locale for passing to <b>pcre_compile()</b> or <b>pcre_exec()</b>. +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> +<P> +The function <b>pcre_fullinfo()</b> is used to find out information about a +compiled pattern; <b>pcre_info()</b> is an obsolete version that returns only +some of the available information, but is retained for backwards compatibility. +The function <b>pcre_version()</b> returns a pointer to a string containing the +version of PCRE and its date of release. +</P> +<P> +The global variables <b>pcre_malloc</b> and <b>pcre_free</b> initially contain +the entry points of the standard <b>malloc()</b> and <b>free()</b> 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> +<P> +The global variables <b>pcre_stack_malloc</b> and <b>pcre_stack_free</b> 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. This 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. +</P> +<P> +The global variable <b>pcre_callout</b> 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 +<a href="pcrecallout.html"><b>pcrecallout</b></a> +documentation. +</P> +<br><a name="SEC3" href="#TOC1">MULTITHREADING</a><br> +<P> +The PCRE functions can be used in multi-threading applications, with the +proviso that the memory management functions pointed to by <b>pcre_malloc</b>, +<b>pcre_free</b>, <b>pcre_stack_malloc</b>, and <b>pcre_stack_free</b>, and the +callout function pointed to by <b>pcre_callout</b>, are shared by all threads. +</P> +<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. +</P> +<br><a name="SEC4" href="#TOC1">SAVING PRECOMPILED PATTERNS FOR LATER USE</a><br> +<P> +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 +<a href="pcreprecompile.html"><b>pcreprecompile</b></a> +documentation. +</P> +<br><a name="SEC5" href="#TOC1">CHECKING BUILD-TIME OPTIONS</a><br> +<P> +<b>int pcre_config(int <i>what</i>, void *<i>where</i>);</b> +</P> +<P> +The function <b>pcre_config()</b> makes it possible for a PCRE client to +discover which optional features have been compiled into the PCRE library. The +<a href="pcrebuild.html"><b>pcrebuild</b></a> +documentation has more details about these optional features. +</P> +<P> +The first argument for <b>pcre_config()</b> 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: +<pre> + PCRE_CONFIG_UTF8 +</pre> +The output is an integer that is set to one if UTF-8 support is available; +otherwise it is set to zero. +<pre> + PCRE_CONFIG_UNICODE_PROPERTIES +</pre> +The output is an integer that is set to one if support for Unicode character +properties is available; otherwise it is set to zero. +<pre> + PCRE_CONFIG_NEWLINE +</pre> +The output is an integer that is set to the value of the code that is used for +the newline character. It is either linefeed (10) or carriage return (13), and +should normally be the standard character for your operating system. +<pre> + PCRE_CONFIG_LINK_SIZE +</pre> +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. +<pre> + PCRE_CONFIG_POSIX_MALLOC_THRESHOLD +</pre> +The output is an integer that contains the threshold above which the POSIX +interface uses <b>malloc()</b> for output vectors. Further details are given in +the +<a href="pcreposix.html"><b>pcreposix</b></a> +documentation. +<pre> + PCRE_CONFIG_MATCH_LIMIT +</pre> +The output is an integer that gives the default limit for the number of +internal matching function calls in a <b>pcre_exec()</b> execution. Further +details are given with <b>pcre_exec()</b> below. +<pre> + PCRE_CONFIG_STACKRECURSE +</pre> +The output is an integer that is set to one if internal recursion 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, <b>pcre_stack_malloc</b> and <b>pcre_stack_free</b> are +called to manage memory blocks on the heap, thus avoiding the use of the stack. +</P> +<br><a name="SEC6" href="#TOC1">COMPILING A PATTERN</a><br> +<P> +<b>pcre *pcre_compile(const char *<i>pattern</i>, int <i>options</i>,</b> +<b>const char **<i>errptr</i>, int *<i>erroffset</i>,</b> +<b>const unsigned char *<i>tableptr</i>);</b> +</P> +<P> +The function <b>pcre_compile()</b> 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 <i>pattern</i> argument. A pointer to a single block of memory +that is obtained via <b>pcre_malloc</b> is returned. This contains the compiled +code and related data. The <b>pcre</b> 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 when it is no longer required. +</P> +<P> +Although the compiled code of a PCRE regex is relocatable, that is, it does not +depend on memory location, the complete <b>pcre</b> data block is not +fully relocatable, because it may contain a copy of the <i>tableptr</i> +argument, which is an address (see below). +</P> +<P> +The <i>options</i> argument contains independent bits 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 +<a href="pcrepattern.html"><b>pcrepattern</b></a> +documentation). For these options, the contents of the <i>options</i> 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. +</P> +<P> +If <i>errptr</i> is NULL, <b>pcre_compile()</b> returns NULL immediately. +Otherwise, if compilation of a pattern fails, <b>pcre_compile()</b> returns +NULL, and sets the variable pointed to by <i>errptr</i> 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 +<i>erroffset</i>, which must not be NULL. If it is, an immediate error is given. +</P> +<P> +If the final argument, <i>tableptr</i>, is NULL, PCRE uses a default set of +character tables that are built when PCRE is compiled, using the default C +locale. Otherwise, <i>tableptr</i> must be an address that is the result of a +call to <b>pcre_maketables()</b>. This value is stored with the compiled +pattern, and used again by <b>pcre_exec()</b>, unless another table pointer is +passed to it. For more discussion, see the section on locale support below. +</P> +<P> +This code fragment shows a typical straightforward call to <b>pcre_compile()</b>: +<pre> + 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 */ +</pre> +The following names for option bits are defined in the <b>pcre.h</b> header +file: +<pre> + PCRE_ANCHORED +</pre> +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. +<pre> + PCRE_AUTO_CALLOUT +</pre> +If this bit is set, <b>pcre_compile()</b> automatically inserts callout items, +all with number 255, before each pattern item. For discussion of the callout +facility, see the +<a href="pcrecallout.html"><b>pcrecallout</b></a> +documentation. +<pre> + PCRE_CASELESS +</pre> +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. When running in UTF-8 mode, case support for +high-valued characters is available only when PCRE is built with Unicode +character property support. +<pre> + PCRE_DOLLAR_ENDONLY +</pre> +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, and no way to set it within +a pattern. +<pre> + PCRE_DOTALL +</pre> +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, and it can be changed within a pattern by a +(?s) option setting. A negative class such as [^a] always matches a newline +character, independent of the setting of this option. +<pre> + PCRE_EXTENDED +</pre> +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 character, +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. +</P> +<P> +This option 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. +<pre> + PCRE_EXTRA +</pre> +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. +<pre> + PCRE_MULTILINE +</pre> +By default, PCRE treats the subject string as consisting of a single line of +characters (even if it actually contains 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. +</P> +<P> +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, and it can be changed within a pattern by a (?m) option +setting. If there are no "\n" characters in a subject string, or no +occurrences of ^ or $ in a pattern, setting PCRE_MULTILINE has no effect. +<pre> + PCRE_NO_AUTO_CAPTURE +</pre> +If this option is set, it disables the use of numbered capturing parentheses in +the pattern. Any opening parenthesis that is not followed by ? behaves as if it +were followed by ?: but named parentheses can still be used for capturing (and +they acquire numbers in the usual way). There is no equivalent of this option +in Perl. +<pre> + PCRE_UNGREEDY +</pre> +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. +<pre> + PCRE_UTF8 +</pre> +This option causes PCRE to regard both the pattern and the subject as strings +of UTF-8 characters instead of single-byte character strings. However, it is +available only when PCRE is built to include UTF-8 support. If not, the use +of this option provokes an error. Details of how this option changes the +behaviour of PCRE are given in the +<a href="pcre.html#utf8support">section on UTF-8 support</a> +in the main +<a href="pcre.html"><b>pcre</b></a> +page. +<pre> + PCRE_NO_UTF8_CHECK +</pre> +When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string is +automatically checked. If an invalid UTF-8 sequence of bytes is found, +<b>pcre_compile()</b> returns an error. If you already know that your pattern is +valid, and you want to skip this check for performance reasons, you can set the +PCRE_NO_UTF8_CHECK option. When it is set, the effect of passing an invalid +UTF-8 string as a pattern is undefined. It may cause your program to crash. +Note that this option can also be passed to <b>pcre_exec()</b>, to suppress the +UTF-8 validity checking of subject strings. +</P> +<br><a name="SEC7" href="#TOC1">STUDYING A PATTERN</a><br> +<P> +<b>pcre_extra *pcre_study(const pcre *<i>code</i>, int <i>options</i>,</b> +<b>const char **<i>errptr</i>);</b> +</P> +<P> +If a compiled 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 <b>pcre_study()</b> takes a pointer to a compiled pattern as its first +argument. If studying the pattern produces additional information that will +help speed up matching, <b>pcre_study()</b> returns a pointer to a +<b>pcre_extra</b> block, in which the <i>study_data</i> field points to the +results of the study. +</P> +<P> +The returned value from <b>pcre_study()</b> can be passed directly to +<b>pcre_exec()</b>. However, a <b>pcre_extra</b> block also contains other +fields that can be set by the caller before the block is passed; these are +described +<a href="#extradata">below</a> +in the section on matching a pattern. +</P> +<P> +If studying the pattern does not produce any additional information, +<b>pcre_study()</b> returns NULL. In that circumstance, if the calling program +wants to pass any of the other fields to <b>pcre_exec()</b>, it must set up its +own <b>pcre_extra</b> block. +</P> +<P> +The second argument of <b>pcre_study()</b> contains option bits. At present, no +options are defined, and this argument should always be zero. +</P> +<P> +The third argument for <b>pcre_study()</b> is a pointer for 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. You should +therefore test the error pointer for NULL after calling <b>pcre_study()</b>, to +be sure that it has run successfully. +</P> +<P> +This is a typical call to <b>pcre_study</b>(): +<pre> + pcre_extra *pe; + pe = pcre_study( + re, /* result of pcre_compile() */ + 0, /* no options exist */ + &error); /* set to NULL or points to a message */ +</pre> +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 +bytes is created. +<a name="localesupport"></a></P> +<br><a name="SEC8" href="#TOC1">LOCALE SUPPORT</a><br> +<P> +PCRE handles caseless matching, and determines whether characters are letters, +digits, or whatever, by reference to a set of tables, indexed by character +value. (When running in UTF-8 mode, this applies only to characters with codes +less than 128. Higher-valued codes never match escapes such as \w or \d, but +can be tested with \p if PCRE is built with Unicode character property +support.) +</P> +<P> +An internal set of tables is created in the default C locale when PCRE is +built. This is used when the final argument of <b>pcre_compile()</b> is NULL, +and is sufficient for many applications. An alternative set of tables can, +however, be supplied. These may be created in a different locale from the +default. As more and more applications change to using Unicode, the need for +this locale support is expected to die away. +</P> +<P> +External tables are built by calling the <b>pcre_maketables()</b> function, +which has no arguments, in the relevant locale. The result can then be passed +to <b>pcre_compile()</b> or <b>pcre_exec()</b> as often as necessary. For +example, to build and use tables that are appropriate for the French locale +(where accented characters with values greater than 128 are treated as letters), +the following code could be used: +<pre> + setlocale(LC_CTYPE, "fr_FR"); + tables = pcre_maketables(); + re = pcre_compile(..., tables); +</pre> +When <b>pcre_maketables()</b> runs, the tables are built in memory that is +obtained via <b>pcre_malloc</b>. It is the caller's responsibility to ensure +that the memory containing the tables remains available for as long as it is +needed. +</P> +<P> +The pointer that is passed to <b>pcre_compile()</b> is saved with the compiled +pattern, and the same tables are used via this pointer by <b>pcre_study()</b> +and normally also by <b>pcre_exec()</b>. Thus, by default, for any single +pattern, compilation, studying and matching all happen in the same locale, but +different patterns can be compiled in different locales. +</P> +<P> +It is possible to pass a table pointer or NULL (indicating the use of the +internal tables) to <b>pcre_exec()</b>. Although not intended for this purpose, +this facility could be used to match a pattern in a different locale from the +one in which it was compiled. Passing table pointers at run time is discussed +below in the section on matching a pattern. +</P> +<br><a name="SEC9" href="#TOC1">INFORMATION ABOUT A PATTERN</a><br> +<P> +<b>int pcre_fullinfo(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> +<b>int <i>what</i>, void *<i>where</i>);</b> +</P> +<P> +The <b>pcre_fullinfo()</b> function returns information about a compiled +pattern. It replaces the obsolete <b>pcre_info()</b> function, which is +nevertheless retained for backwards compability (and is documented below). +</P> +<P> +The first argument for <b>pcre_fullinfo()</b> is a pointer to the compiled +pattern. The second argument is the result of <b>pcre_study()</b>, or NULL if +the pattern was not studied. The third argument specifies which piece of +information is required, and 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 +the following negative numbers: +<pre> + PCRE_ERROR_NULL the argument <i>code</i> was NULL + the argument <i>where</i> was NULL + PCRE_ERROR_BADMAGIC the "magic number" was not found + PCRE_ERROR_BADOPTION the value of <i>what</i> was invalid +</pre> +The "magic number" is placed at the start of each compiled pattern as an simple +check against passing an arbitrary memory pointer. Here is a typical call of +<b>pcre_fullinfo()</b>, to obtain the length of the compiled pattern: +<pre> + int rc; + unsigned long int length; + rc = pcre_fullinfo( + re, /* result of pcre_compile() */ + pe, /* result of pcre_study(), or NULL */ + PCRE_INFO_SIZE, /* what is required */ + &length); /* where to put the data */ +</pre> +The possible values for the third argument are defined in <b>pcre.h</b>, and are +as follows: +<pre> + PCRE_INFO_BACKREFMAX +</pre> +Return the number of the highest back reference in the pattern. The fourth +argument should point to an <b>int</b> variable. Zero is returned if there are +no back references. +<pre> + PCRE_INFO_CAPTURECOUNT +</pre> +Return the number of capturing subpatterns in the pattern. The fourth argument +should point to an <b>int</b> variable. +<pre> + PCRE_INFO_DEFAULTTABLES +</pre> +Return a pointer to the internal default character tables within PCRE. The +fourth argument should point to an <b>unsigned char *</b> variable. This +information call is provided for internal use by the <b>pcre_study()</b> +function. External callers can cause PCRE to use its internal tables by passing +a NULL table pointer. +<pre> + PCRE_INFO_FIRSTBYTE +</pre> +Return information about the first byte of any matched string, for a +non-anchored pattern. (This option used to be called PCRE_INFO_FIRSTCHAR; the +old name is still recognized for backwards compatibility.) +</P> +<P> +If there is a fixed first byte, for example, from a pattern such as +(cat|cow|coyote), it is returned in the integer pointed to by <i>where</i>. +Otherwise, if either +<br> +<br> +(a) the pattern was compiled with the PCRE_MULTILINE option, and every branch +starts with "^", or +<br> +<br> +(b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not set +(if it were set, the pattern would be anchored), +<br> +<br> +-1 is returned, indicating that the pattern matches only at the start of a +subject string or after any newline within the string. Otherwise -2 is +returned. For anchored patterns, -2 is returned. +<pre> + PCRE_INFO_FIRSTTABLE +</pre> +If the pattern was studied, and this resulted in the construction of a 256-bit +table indicating a fixed set of bytes for the first byte in any matching +string, a pointer to the table is returned. Otherwise NULL is returned. The +fourth argument should point to an <b>unsigned char *</b> variable. +<pre> + PCRE_INFO_LASTLITERAL +</pre> +Return the value of the rightmost literal byte that must exist in any matched +string, other than at its start, if such a byte has been recorded. The fourth +argument should point to an <b>int</b> variable. If there is no such byte, -1 is +returned. For anchored patterns, a last literal byte is recorded only if it +follows something of variable length. For example, for the pattern +/^a\d+z\d+/ the returned value is "z", but for /^a\dz\d/ the returned value +is -1. +<pre> + PCRE_INFO_NAMECOUNT + PCRE_INFO_NAMEENTRYSIZE + PCRE_INFO_NAMETABLE +</pre> +PCRE supports the use of named as well as numbered capturing parentheses. The +names are just an additional way of identifying the parentheses, which still +acquire numbers. A convenience function called <b>pcre_get_named_substring()</b> +is provided for extracting an individual captured substring by name. It is also +possible to extract the data directly, by first converting the name to a number +in order to access the correct pointers in the output vector (described with +<b>pcre_exec()</b> below). To do the conversion, you need to use the +name-to-number map, which is described by these three values. +</P> +<P> +The map consists of a number of fixed-size entries. PCRE_INFO_NAMECOUNT gives +the number of entries, and PCRE_INFO_NAMEENTRYSIZE gives the size of each +entry; both of these return an <b>int</b> value. The entry size depends on the +length of the longest name. PCRE_INFO_NAMETABLE returns a pointer to the first +entry of the table (a pointer to <b>char</b>). The first two bytes of each entry +are the number of the capturing parenthesis, most significant byte first. The +rest of the entry is the corresponding name, zero terminated. The names are in +alphabetical order. For example, consider the following pattern (assume +PCRE_EXTENDED is set, so white space - including newlines - is ignored): +<pre> + (?P<date> (?P<year>(\d\d)?\d\d) - (?P<month>\d\d) - (?P<day>\d\d) ) +</pre> +There are four named subpatterns, so the table has four entries, and each entry +in the table is eight bytes long. The table is as follows, with non-printing +bytes shows in hexadecimal, and undefined bytes shown as ??: +<pre> + 00 01 d a t e 00 ?? + 00 05 d a y 00 ?? ?? + 00 04 m o n t h 00 + 00 02 y e a r 00 ?? +</pre> +When writing code to extract data from named subpatterns using the +name-to-number map, remember that the length of each entry is likely to be +different for each compiled pattern. +<pre> + PCRE_INFO_OPTIONS +</pre> +Return a copy of the options with which the pattern was compiled. The fourth +argument should point to an <b>unsigned long int</b> variable. These option bits +are those specified in the call to <b>pcre_compile()</b>, modified by any +top-level option settings within the pattern itself. +</P> +<P> +A pattern is automatically anchored by PCRE if all of its top-level +alternatives begin with one of the following: +<pre> + ^ unless PCRE_MULTILINE is set + \A always + \G always + .* if PCRE_DOTALL is set and there are no back references to the subpattern in which .* appears +</pre> +For such patterns, the PCRE_ANCHORED bit is set in the options returned by +<b>pcre_fullinfo()</b>. +<pre> + PCRE_INFO_SIZE +</pre> +Return the size of the compiled pattern, that is, the value that was passed as +the argument to <b>pcre_malloc()</b> when PCRE was getting memory in which to +place the compiled data. The fourth argument should point to a <b>size_t</b> +variable. +<pre> + PCRE_INFO_STUDYSIZE +</pre> +Return the size of the data block pointed to by the <i>study_data</i> field in +a <b>pcre_extra</b> block. That is, it is the value that was passed to +<b>pcre_malloc()</b> when PCRE was getting memory into which to place the data +created by <b>pcre_study()</b>. The fourth argument should point to a +<b>size_t</b> variable. +</P> +<br><a name="SEC10" href="#TOC1">OBSOLETE INFO FUNCTION</a><br> +<P> +<b>int pcre_info(const pcre *<i>code</i>, int *<i>optptr</i>, int</b> +<b>*<i>firstcharptr</i>);</b> +</P> +<P> +The <b>pcre_info()</b> function is now obsolete because its interface is too +restrictive to return all the available data about a compiled pattern. New +programs should use <b>pcre_fullinfo()</b> instead. The yield of +<b>pcre_info()</b> is the number of capturing subpatterns, or one of the +following negative numbers: +<pre> + PCRE_ERROR_NULL the argument <i>code</i> was NULL + PCRE_ERROR_BADMAGIC the "magic number" was not found +</pre> +If the <i>optptr</i> argument is not NULL, a copy of the options with which the +pattern was compiled is placed in the integer it points to (see +PCRE_INFO_OPTIONS above). +</P> +<P> +If the pattern is not anchored and the <i>firstcharptr</i> argument is not NULL, +it is used to pass back information about the first character of any matched +string (see PCRE_INFO_FIRSTBYTE above). +</P> +<br><a name="SEC11" href="#TOC1">MATCHING A PATTERN</a><br> +<P> +<b>int pcre_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> +<b>const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b> +<b>int <i>options</i>, int *<i>ovector</i>, int <i>ovecsize</i>);</b> +</P> +<P> +The function <b>pcre_exec()</b> is called to match a subject string against a +compiled pattern, which is passed in the <i>code</i> argument. If the +pattern has been studied, the result of the study should be passed in the +<i>extra</i> argument. +</P> +<P> +In most applications, the pattern will have been compiled (and optionally +studied) in the same process that calls <b>pcre_exec()</b>. However, it is +possible to save compiled patterns and study data, and then use them later +in different processes, possibly even on different hosts. For a discussion +about this, see the +<a href="pcreprecompile.html"><b>pcreprecompile</b></a> +documentation. +</P> +<P> +Here is an example of a simple call to <b>pcre_exec()</b>: +<pre> + int rc; + int ovector[30]; + rc = pcre_exec( + re, /* result of pcre_compile() */ + NULL, /* we didn't study the pattern */ + "some string", /* the subject string */ + 11, /* the length of the subject string */ + 0, /* start at offset 0 in the subject */ + 0, /* default options */ + ovector, /* vector of integers for substring information */ + 30); /* number of elements in the vector (NOT size in bytes) */ +<a name="extradata"></a></PRE> +</P> +<br><b> +Extra data for <b>pcre_exec()</b> +</b><br> +<P> +If the <i>extra</i> argument is not NULL, it must point to a <b>pcre_extra</b> +data block. The <b>pcre_study()</b> function returns such a block (when it +doesn't return NULL), but you can also create one for yourself, and pass +additional information in it. The fields in a <b>pcre_extra</b> block are as +follows: +<pre> + unsigned long int <i>flags</i>; + void *<i>study_data</i>; + unsigned long int <i>match_limit</i>; + void *<i>callout_data</i>; + const unsigned char *<i>tables</i>; +</pre> +The <i>flags</i> field is a bitmap that specifies which of the other fields +are set. The flag bits are: +<pre> + PCRE_EXTRA_STUDY_DATA + PCRE_EXTRA_MATCH_LIMIT + PCRE_EXTRA_CALLOUT_DATA + PCRE_EXTRA_TABLES +</pre> +Other flag bits should be set to zero. The <i>study_data</i> field is set in the +<b>pcre_extra</b> block that is returned by <b>pcre_study()</b>, together with +the appropriate flag bit. You should not set this yourself, but you may add to +the block by setting the other fields and their corresponding flag bits. +</P> +<P> +The <i>match_limit</i> field provides a means of preventing PCRE from using up a +vast amount of resources when running patterns that are not going to match, +but which have a very large number of possibilities in their search trees. The +classic example is the use of nested unlimited repeats. +</P> +<P> +Internally, PCRE uses a function called <b>match()</b> which it calls repeatedly +(sometimes recursively). The limit is imposed on the number of times this +function is called during a match, which has the effect of limiting the amount +of recursion and backtracking that can take place. For patterns that are not +anchored, the count starts from zero for each position in the subject string. +</P> +<P> +The default limit for the library can be set when PCRE is built; the default +default is 10 million, which handles all but the most extreme cases. You can +reduce the default by suppling <b>pcre_exec()</b> with a <b>pcre_extra</b> block +in which <i>match_limit</i> is set to a smaller value, and +PCRE_EXTRA_MATCH_LIMIT is set in the <i>flags</i> field. If the limit is +exceeded, <b>pcre_exec()</b> returns PCRE_ERROR_MATCHLIMIT. +</P> +<P> +The <i>pcre_callout</i> field is used in conjunction with the "callout" feature, +which is described in the +<a href="pcrecallout.html"><b>pcrecallout</b></a> +documentation. +</P> +<P> +The <i>tables</i> field is used to pass a character tables pointer to +<b>pcre_exec()</b>; this overrides the value that is stored with the compiled +pattern. A non-NULL value is stored with the compiled pattern only if custom +tables were supplied to <b>pcre_compile()</b> via its <i>tableptr</i> argument. +If NULL is passed to <b>pcre_exec()</b> using this mechanism, it forces PCRE's +internal tables to be used. This facility is helpful when re-using patterns +that have been saved after compiling with an external set of tables, because +the external tables might be at a different address when <b>pcre_exec()</b> is +called. See the +<a href="pcreprecompile.html"><b>pcreprecompile</b></a> +documentation for a discussion of saving compiled patterns for later use. +</P> +<br><b> +Option bits for <b>pcre_exec()</b> +</b><br> +<P> +The unused bits of the <i>options</i> argument for <b>pcre_exec()</b> must be +zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NOTBOL, +PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NO_UTF8_CHECK and PCRE_PARTIAL. +<pre> + PCRE_ANCHORED +</pre> +The PCRE_ANCHORED option limits <b>pcre_exec()</b> to matching at the first +matching position. If a pattern was compiled with PCRE_ANCHORED, or turned out +to be anchored by virtue of its contents, it cannot be made unachored at +matching time. +<pre> + PCRE_NOTBOL +</pre> +This option specifies that first character of the subject string is not the +beginning of a line, so the circumflex metacharacter should not match before +it. Setting this without PCRE_MULTILINE (at compile time) causes circumflex +never to match. This option affects only the behaviour of the circumflex +metacharacter. It does not affect \A. +<pre> + PCRE_NOTEOL +</pre> +This option specifies that the end of the subject string is not the end of a +line, so the dollar metacharacter should not match it nor (except in multiline +mode) a newline immediately before it. Setting this without PCRE_MULTILINE (at +compile time) causes dollar never to match. This option affects only the +behaviour of the dollar metacharacter. It does not affect \Z or \z. +<pre> + PCRE_NOTEMPTY +</pre> +An empty string is not considered to be a valid match if this option is set. If +there are alternatives in the pattern, they are tried. If all the alternatives +match the empty string, the entire match fails. For example, if the pattern +<pre> + a?b? +</pre> +is applied to a string not beginning with "a" or "b", it matches the empty +string at the start of the subject. With PCRE_NOTEMPTY set, this match is not +valid, so PCRE searches further into the string for occurrences of "a" or "b". +</P> +<P> +Perl has no direct equivalent of PCRE_NOTEMPTY, but it does make a special case +of a pattern match of the empty string within its <b>split()</b> function, and +when using the /g modifier. It is possible to emulate Perl's behaviour after +matching a null string by first trying the match again at the same offset with +PCRE_NOTEMPTY and PCRE_ANCHORED, and then if that fails by advancing the +starting offset (see below) and trying an ordinary match again. There is some +code that demonstrates how to do this in the <i>pcredemo.c</i> sample program. +<pre> + PCRE_NO_UTF8_CHECK +</pre> +When PCRE_UTF8 is set at compile time, the validity of the subject as a UTF-8 +string is automatically checked when <b>pcre_exec()</b> is subsequently called. +The value of <i>startoffset</i> is also checked to ensure that it points to the +start of a UTF-8 character. If an invalid UTF-8 sequence of bytes is found, +<b>pcre_exec()</b> returns the error PCRE_ERROR_BADUTF8. If <i>startoffset</i> +contains an invalid value, PCRE_ERROR_BADUTF8_OFFSET is returned. +</P> +<P> +If you already know that your subject is valid, and you want to skip these +checks for performance reasons, you can set the PCRE_NO_UTF8_CHECK option when +calling <b>pcre_exec()</b>. You might want to do this for the second and +subsequent calls to <b>pcre_exec()</b> if you are making repeated calls to find +all the matches in a single subject string. However, you should be sure that +the value of <i>startoffset</i> points to the start of a UTF-8 character. When +PCRE_NO_UTF8_CHECK is set, the effect of passing an invalid UTF-8 string as a +subject, or a value of <i>startoffset</i> that does not point to the start of a +UTF-8 character, is undefined. Your program may crash. +<pre> + PCRE_PARTIAL +</pre> +This option turns on the partial matching feature. If the subject string fails +to match the pattern, but at some point during the matching process the end of +the subject was reached (that is, the subject partially matches the pattern and +the failure to match occurred only because there were not enough subject +characters), <b>pcre_exec()</b> returns PCRE_ERROR_PARTIAL instead of +PCRE_ERROR_NOMATCH. When PCRE_PARTIAL is used, there are restrictions on what +may appear in the pattern. These are discussed in the +<a href="pcrepartial.html"><b>pcrepartial</b></a> +documentation. +</P> +<br><b> +The string to be matched by <b>pcre_exec()</b> +</b><br> +<P> +The subject string is passed to <b>pcre_exec()</b> as a pointer in +<i>subject</i>, a length in <i>length</i>, and a starting byte offset in +<i>startoffset</i>. In UTF-8 mode, the byte offset must point to the start of a +UTF-8 character. Unlike the pattern string, the subject may contain binary zero +bytes. When the starting offset is zero, the search for a match starts at the +beginning of the subject, and this is by far the most common case. +</P> +<P> +A non-zero starting offset is useful when searching for another match in the +same subject by calling <b>pcre_exec()</b> again after a previous success. +Setting <i>startoffset</i> differs from just passing over a shortened string and +setting PCRE_NOTBOL in the case of a pattern that begins with any kind of +lookbehind. For example, consider the pattern +<pre> + \Biss\B +</pre> +which finds occurrences of "iss" in the middle of words. (\B matches only if +the current position in the subject is not a word boundary.) When applied to +the string "Mississipi" the first call to <b>pcre_exec()</b> finds the first +occurrence. If <b>pcre_exec()</b> is called again with just the remainder of the +subject, namely "issipi", it does not match, because \B is always false at the +start of the subject, which is deemed to be a word boundary. However, if +<b>pcre_exec()</b> is passed the entire string again, but with <i>startoffset</i> +set to 4, it finds the second occurrence of "iss" because it is able to look +behind the starting point to discover that it is preceded by a letter. +</P> +<P> +If a non-zero starting offset is passed when the pattern is anchored, one +attempt to match at the given offset is made. This can only succeed if the +pattern does not require the match to be at the start of the subject. +</P> +<br><b> +How <b>pcre_exec()</b> returns captured substrings +</b><br> +<P> +In general, a pattern matches a certain portion of the subject, and in +addition, further substrings from the subject may be picked out by parts of the +pattern. Following the usage in Jeffrey Friedl's book, this is called +"capturing" in what follows, and the phrase "capturing subpattern" is used for +a fragment of a pattern that picks out a substring. PCRE supports several other +kinds of parenthesized subpattern that do not cause substrings to be captured. +</P> +<P> +Captured substrings are returned to the caller via a vector of integer offsets +whose address is passed in <i>ovector</i>. The number of elements in the vector +is passed in <i>ovecsize</i>, which must be a non-negative number. <b>Note</b>: +this argument is NOT the size of <i>ovector</i> in bytes. +</P> +<P> +The first two-thirds of the vector is used to pass back captured substrings, +each substring using a pair of integers. The remaining third of the vector is +used as workspace by <b>pcre_exec()</b> while matching capturing subpatterns, +and is not available for passing back information. The length passed in +<i>ovecsize</i> should always be a multiple of three. If it is not, it is +rounded down. +</P> +<P> +When a match is successful, information about captured substrings is returned +in pairs of integers, starting at the beginning of <i>ovector</i>, and +continuing up to two-thirds of its length at the most. The first element of a +pair is set to the offset of the first character in a substring, and the second +is set to the offset of the first character after the end of a substring. The +first pair, <i>ovector[0]</i> and <i>ovector[1]</i>, identify the portion of the +subject string matched by the entire pattern. The next pair is used for the +first capturing subpattern, and so on. The value returned by <b>pcre_exec()</b> +is the number of pairs that have been set. If there are no capturing +subpatterns, the return value from a successful match is 1, indicating that +just the first pair of offsets has been set. +</P> +<P> +Some convenience functions are provided for extracting the captured substrings +as separate strings. These are described in the following section. +</P> +<P> +It is possible for an capturing subpattern number <i>n+1</i> to match some +part of the subject when subpattern <i>n</i> has not been used at all. For +example, if the string "abc" is matched against the pattern (a|(z))(bc) +subpatterns 1 and 3 are matched, but 2 is not. When this happens, both offset +values corresponding to the unused subpattern are set to -1. +</P> +<P> +If a capturing subpattern is matched repeatedly, it is the last portion of the +string that it matched that is returned. +</P> +<P> +If the vector is too small to hold all the captured substring offsets, it is +used as far as possible (up to two-thirds of its length), and the function +returns a value of zero. In particular, if the substring offsets are not of +interest, <b>pcre_exec()</b> may be called with <i>ovector</i> passed as NULL and +<i>ovecsize</i> as zero. However, if the pattern contains back references and +the <i>ovector</i> is not big enough to remember the related substrings, PCRE +has to get additional memory for use during matching. Thus it is usually +advisable to supply an <i>ovector</i>. +</P> +<P> +Note that <b>pcre_info()</b> can be used to find out how many capturing +subpatterns there are in a compiled pattern. The smallest size for +<i>ovector</i> that will allow for <i>n</i> captured substrings, in addition to +the offsets of the substring matched by the whole pattern, is (<i>n</i>+1)*3. +</P> +<br><b> +Return values from <b>pcre_exec()</b> +</b><br> +<P> +If <b>pcre_exec()</b> fails, it returns a negative number. The following are +defined in the header file: +<pre> + PCRE_ERROR_NOMATCH (-1) +</pre> +The subject string did not match the pattern. +<pre> + PCRE_ERROR_NULL (-2) +</pre> +Either <i>code</i> or <i>subject</i> was passed as NULL, or <i>ovector</i> was +NULL and <i>ovecsize</i> was not zero. +<pre> + PCRE_ERROR_BADOPTION (-3) +</pre> +An unrecognized bit was set in the <i>options</i> argument. +<pre> + PCRE_ERROR_BADMAGIC (-4) +</pre> +PCRE stores a 4-byte "magic number" at the start of the compiled code, to catch +the case when it is passed a junk pointer and to detect when a pattern that was +compiled in an environment of one endianness is run in an environment with the +other endianness. This is the error that PCRE gives when the magic number is +not present. +<pre> + PCRE_ERROR_UNKNOWN_NODE (-5) +</pre> +While running the pattern match, an unknown item was encountered in the +compiled pattern. This error could be caused by a bug in PCRE or by overwriting +of the compiled pattern. +<pre> + PCRE_ERROR_NOMEMORY (-6) +</pre> +If a pattern contains back references, but the <i>ovector</i> that is passed to +<b>pcre_exec()</b> is not big enough to remember the referenced substrings, PCRE +gets a block of memory at the start of matching to use for this purpose. If the +call via <b>pcre_malloc()</b> fails, this error is given. The memory is +automatically freed at the end of matching. +<pre> + PCRE_ERROR_NOSUBSTRING (-7) +</pre> +This error is used by the <b>pcre_copy_substring()</b>, +<b>pcre_get_substring()</b>, and <b>pcre_get_substring_list()</b> functions (see +below). It is never returned by <b>pcre_exec()</b>. +<pre> + PCRE_ERROR_MATCHLIMIT (-8) +</pre> +The recursion and backtracking limit, as specified by the <i>match_limit</i> +field in a <b>pcre_extra</b> structure (or defaulted) was reached. See the +description above. +<pre> + PCRE_ERROR_CALLOUT (-9) +</pre> +This error is never generated by <b>pcre_exec()</b> itself. It is provided for +use by callout functions that want to yield a distinctive error code. See the +<a href="pcrecallout.html"><b>pcrecallout</b></a> +documentation for details. +<pre> + PCRE_ERROR_BADUTF8 (-10) +</pre> +A string that contains an invalid UTF-8 byte sequence was passed as a subject. +<pre> + PCRE_ERROR_BADUTF8_OFFSET (-11) +</pre> +The UTF-8 byte sequence that was passed as a subject was valid, but the value +of <i>startoffset</i> did not point to the beginning of a UTF-8 character. +<pre> + PCRE_ERROR_PARTIAL (-12) +</pre> +The subject string did not match, but it did match partially. See the +<a href="pcrepartial.html"><b>pcrepartial</b></a> +documentation for details of partial matching. +<pre> + PCRE_ERROR_BAD_PARTIAL (-13) +</pre> +The PCRE_PARTIAL option was used with a compiled pattern containing items that +are not supported for partial matching. See the +<a href="pcrepartial.html"><b>pcrepartial</b></a> +documentation for details of partial matching. +<pre> + PCRE_ERROR_INTERNAL (-14) +</pre> +An unexpected internal error has occurred. This error could be caused by a bug +in PCRE or by overwriting of the compiled pattern. +<pre> + PCRE_ERROR_BADCOUNT (-15) +</pre> +This error is given if the value of the <i>ovecsize</i> argument is negative. +</P> +<br><a name="SEC12" href="#TOC1">EXTRACTING CAPTURED SUBSTRINGS BY NUMBER</a><br> +<P> +<b>int pcre_copy_substring(const char *<i>subject</i>, int *<i>ovector</i>,</b> +<b>int <i>stringcount</i>, int <i>stringnumber</i>, char *<i>buffer</i>,</b> +<b>int <i>buffersize</i>);</b> +</P> +<P> +<b>int pcre_get_substring(const char *<i>subject</i>, int *<i>ovector</i>,</b> +<b>int <i>stringcount</i>, int <i>stringnumber</i>,</b> +<b>const char **<i>stringptr</i>);</b> +</P> +<P> +<b>int pcre_get_substring_list(const char *<i>subject</i>,</b> +<b>int *<i>ovector</i>, int <i>stringcount</i>, const char ***<i>listptr</i>);</b> +</P> +<P> +Captured substrings can be accessed directly by using the offsets returned by +<b>pcre_exec()</b> in <i>ovector</i>. For convenience, the functions +<b>pcre_copy_substring()</b>, <b>pcre_get_substring()</b>, and +<b>pcre_get_substring_list()</b> are provided for extracting captured substrings +as new, separate, zero-terminated strings. These functions identify substrings +by number. The next section describes functions for extracting named +substrings. A substring that contains a binary zero is correctly extracted and +has a further zero added on the end, but the result is not, of course, +a C string. +</P> +<P> +The first three arguments are the same for all three of these functions: +<i>subject</i> is the subject string that has just been successfully matched, +<i>ovector</i> is a pointer to the vector of integer offsets that was passed to +<b>pcre_exec()</b>, and <i>stringcount</i> is the number of substrings that were +captured by the match, including the substring that matched the entire regular +expression. This is the value returned by <b>pcre_exec()</b> if it is greater +than zero. If <b>pcre_exec()</b> returned zero, indicating that it ran out of +space in <i>ovector</i>, the value passed as <i>stringcount</i> should be the +number of elements in the vector divided by three. +</P> +<P> +The functions <b>pcre_copy_substring()</b> and <b>pcre_get_substring()</b> +extract a single substring, whose number is given as <i>stringnumber</i>. A +value of zero extracts the substring that matched the entire pattern, whereas +higher values extract the captured substrings. For <b>pcre_copy_substring()</b>, +the string is placed in <i>buffer</i>, whose length is given by +<i>buffersize</i>, while for <b>pcre_get_substring()</b> a new block of memory is +obtained via <b>pcre_malloc</b>, and its address is returned via +<i>stringptr</i>. The yield of the function is the length of the string, not +including the terminating zero, or one of +<pre> + PCRE_ERROR_NOMEMORY (-6) +</pre> +The buffer was too small for <b>pcre_copy_substring()</b>, or the attempt to get +memory failed for <b>pcre_get_substring()</b>. +<pre> + PCRE_ERROR_NOSUBSTRING (-7) +</pre> +There is no substring whose number is <i>stringnumber</i>. +</P> +<P> +The <b>pcre_get_substring_list()</b> function extracts all available substrings +and builds a list of pointers to them. All this is done in a single block of +memory that is obtained via <b>pcre_malloc</b>. The address of the memory block +is returned via <i>listptr</i>, 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 +<pre> + PCRE_ERROR_NOMEMORY (-6) +</pre> +if the attempt to get the memory block failed. +</P> +<P> +When any of these functions encounter a substring that is unset, which can +happen when capturing subpattern number <i>n+1</i> matches some part of the +subject, but subpattern <i>n</i> 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 <i>ovector</i>, which is negative for unset +substrings. +</P> +<P> +The two convenience functions <b>pcre_free_substring()</b> and +<b>pcre_free_substring_list()</b> can be used to free the memory returned by +a previous call of <b>pcre_get_substring()</b> or +<b>pcre_get_substring_list()</b>, respectively. They do nothing more than call +the function pointed to by <b>pcre_free</b>, which of course could be called +directly from a C program. However, PCRE is used in some situations where it is +linked via a special interface to another programming language which cannot use +<b>pcre_free</b> directly; it is for these cases that the functions are +provided. +</P> +<br><a name="SEC13" href="#TOC1">EXTRACTING CAPTURED SUBSTRINGS BY NAME</a><br> +<P> +<b>int pcre_get_stringnumber(const pcre *<i>code</i>,</b> +<b>const char *<i>name</i>);</b> +</P> +<P> +<b>int pcre_copy_named_substring(const pcre *<i>code</i>,</b> +<b>const char *<i>subject</i>, int *<i>ovector</i>,</b> +<b>int <i>stringcount</i>, const char *<i>stringname</i>,</b> +<b>char *<i>buffer</i>, int <i>buffersize</i>);</b> +</P> +<P> +<b>int pcre_get_named_substring(const pcre *<i>code</i>,</b> +<b>const char *<i>subject</i>, int *<i>ovector</i>,</b> +<b>int <i>stringcount</i>, const char *<i>stringname</i>,</b> +<b>const char **<i>stringptr</i>);</b> +</P> +<P> +To extract a substring by name, you first have to find associated number. +For example, for this pattern +<pre> + (a+)b(?<xxx>\d+)... +</pre> +the number of the subpattern called "xxx" is 2. You can find the number from +the name by calling <b>pcre_get_stringnumber()</b>. The first argument is the +compiled pattern, and the second is the name. The yield of the function is the +subpattern number, or PCRE_ERROR_NOSUBSTRING (-7) if there is no subpattern of +that name. +</P> +<P> +Given the number, you can extract the substring directly, or use one of the +functions described in the previous section. For convenience, there are also +two functions that do the whole job. +</P> +<P> +Most of the arguments of <i>pcre_copy_named_substring()</i> and +<i>pcre_get_named_substring()</i> are the same as those for the similarly named +functions that extract by number. As these are described in the previous +section, they are not re-described here. There are just two differences: +</P> +<P> +First, instead of a substring number, a substring name is given. Second, there +is an extra argument, given at the start, which is a pointer to the compiled +pattern. This is needed in order to gain access to the name-to-number +translation table. +</P> +<P> +These functions call <b>pcre_get_stringnumber()</b>, and if it succeeds, they +then call <i>pcre_copy_substring()</i> or <i>pcre_get_substring()</i>, as +appropriate. +</P> +<P> +Last updated: 09 September 2004 +<br> +Copyright © 1997-2004 University of Cambridge. +<p> +Return to the <a href="index.html">PCRE index page</a>. +</p> |