Removed the documentation files because they were making the httpd

source checkout too large, added a README file pointing to the reference
copy of the docs in the PCRE vendor branch


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@106747 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 0 insertions, 1288 deletions

diff --git a/srclib/pcre/doc/pcreapi.3 b/srclib/pcre/doc/pcreapi.3
deleted file mode 100644
index 42a4e59c96..0000000000
--- a/srclib/pcre/doc/pcreapi.3
+++ /dev/null
@@ -1,1288 +0,0 @@
-.TH PCRE 3
-.SH NAME
-PCRE - Perl-compatible regular expressions
-.SH "PCRE NATIVE API"
-.rs
-.sp
-.B #include <pcre.h>
-.PP
-.SM
-.br
-.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
-.br
-.B pcre_extra *pcre_study(const pcre *\fIcode\fP, int \fIoptions\fP,
-.ti +5n
-.B const char **\fIerrptr\fP);
-.PP
-.br
-.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
-.br
-.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
-.br
-.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
-.br
-.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
-.br
-.B int pcre_get_stringnumber(const pcre *\fIcode\fP,
-.ti +5n
-.B const char *\fIname\fP);
-.PP
-.br
-.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
-.br
-.B int pcre_get_substring_list(const char *\fIsubject\fP,
-.ti +5n
-.B int *\fIovector\fP, int \fIstringcount\fP, "const char ***\fIlistptr\fP);"
-.PP
-.br
-.B void pcre_free_substring(const char *\fIstringptr\fP);
-.PP
-.br
-.B void pcre_free_substring_list(const char **\fIstringptr\fP);
-.PP
-.br
-.B const unsigned char *pcre_maketables(void);
-.PP
-.br
-.B int pcre_fullinfo(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP,"
-.ti +5n
-.B int \fIwhat\fP, void *\fIwhere\fP);
-.PP
-.br
-.B int pcre_info(const pcre *\fIcode\fP, int *\fIoptptr\fP, int
-.B *\fIfirstcharptr\fP);
-.PP
-.br
-.B int pcre_config(int \fIwhat\fP, void *\fIwhere\fP);
-.PP
-.br
-.B char *pcre_version(void);
-.PP
-.br
-.B void *(*pcre_malloc)(size_t);
-.PP
-.br
-.B void (*pcre_free)(void *);
-.PP
-.br
-.B void *(*pcre_stack_malloc)(size_t);
-.PP
-.br
-.B void (*pcre_stack_free)(void *);
-.PP
-.br
-.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 is also
-a set of wrapper functions that correspond to the POSIX regular expression API.
-These are described in the
-.\" HREF
-\fBpcreposix\fP
-.\"
-documentation.
-.P
-The native API 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_study()\fP, and \fBpcre_exec()\fP
-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
-\fIpcredemo.c\fP in the source distribution. The
-.\" HREF
-\fBpcresample\fP
-.\"
-documentation describes how to run it.
-.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:
-.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
-.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 or \fBpcre_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 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. 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
-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.
-.
-.
-.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.
-.
-.
-.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 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.
-.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_STACKRECURSE
-.sp
-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, \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);
-.P
-The function \fBpcre_compile()\fP 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 \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 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 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
-.\" 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 option 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. 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 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_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. When running in UTF-8 mode, case support for
-high-valued characters is available only when PCRE is built with Unicode
-character property 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 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.
-.sp
-  PCRE_DOTALL
-.sp
-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.
-.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 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
-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.
-.sp
-  PCRE_EXTRA
-.sp
-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.
-.sp
-  PCRE_MULTILINE
-.sp
-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
-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 "\en" characters in a subject string, or no
-occurrences of ^ or $ in a pattern, setting PCRE_MULTILINE has no effect.
-.sp
-  PCRE_NO_AUTO_CAPTURE
-.sp
-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.
-.sp
-  PCRE_UNGREEDY
-.sp
-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.
-.sp
-  PCRE_UTF8
-.sp
-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
-.\" HTML <a href="pcre.html#utf8support">
-.\" </a>
-section on UTF-8 support
-.\"
-in the main
-.\" HREF
-\fBpcre\fP
-.\"
-page.
-.sp
-  PCRE_NO_UTF8_CHECK
-.sp
-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,
-\fBpcre_compile()\fP 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 \fBpcre_exec()\fP, to suppress the
-UTF-8 validity checking of subject strings.
-.
-.
-.SH "STUDYING A PATTERN"
-.rs
-.sp
-.B pcre_extra *pcre_study(const pcre *\fIcode\fP, int \fIoptions\fP,
-.ti +5n
-.B const char **\fIerrptr\fP);
-.PP
-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 \fBpcre_study()\fP takes a pointer to a compiled pattern as its first
-argument. If studying the pattern produces additional information that will
-help speed up matching, \fBpcre_study()\fP returns a pointer to a
-\fBpcre_extra\fP block, in which the \fIstudy_data\fP field points to the
-results of the study.
-.P
-The returned value from \fBpcre_study()\fP can be passed directly to
-\fBpcre_exec()\fP. However, a \fBpcre_extra\fP block also contains other
-fields that can be set by the caller before the block is passed; these are
-described
-.\" HTML <a href="#extradata">
-.\" </a>
-below
-.\"
-in the section on matching a pattern.
-.P
-If studying the pattern does not produce any additional information,
-\fBpcre_study()\fP returns NULL. In that circumstance, if the calling program
-wants to pass any of the other fields to \fBpcre_exec()\fP, it must set up its
-own \fBpcre_extra\fP block.
-.P
-The second argument of \fBpcre_study()\fP contains option bits. At present, no
-options are defined, and this argument should always be zero.
-.P
-The third argument for \fBpcre_study()\fP 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 \fBpcre_study()\fP, to
-be sure that it has run successfully.
-.P
-This is a typical call to \fBpcre_study\fP():
-.sp
-  pcre_extra *pe;
-  pe = pcre_study(
-    re,             /* result of pcre_compile() */
-    0,              /* no options exist */
-    &error);        /* set to NULL or points to a message */
-.sp
-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.
-.
-.
-.\" HTML <a name="localesupport"></a>
-.SH "LOCALE SUPPORT"
-.rs
-.sp
-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 \ew or \ed, but
-can be tested with \ep if PCRE is built with Unicode character property
-support.)
-.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 \fBpcre_compile()\fP 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
-External tables are built by calling the \fBpcre_maketables()\fP function,
-which has no arguments, in the relevant locale. The result can then be passed
-to \fBpcre_compile()\fP or \fBpcre_exec()\fP 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:
-.sp
-  setlocale(LC_CTYPE, "fr_FR");
-  tables = pcre_maketables();
-  re = pcre_compile(..., tables);
-.sp
-When \fBpcre_maketables()\fP runs, the tables are built in memory that is
-obtained via \fBpcre_malloc\fP. It is the caller's responsibility to ensure
-that the memory containing the tables remains available for as long as it is
-needed.
-.P
-The pointer that is passed to \fBpcre_compile()\fP is saved with the compiled
-pattern, and the same tables are used via this pointer by \fBpcre_study()\fP
-and normally also by \fBpcre_exec()\fP. 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
-It is possible to pass a table pointer or NULL (indicating the use of the
-internal tables) to \fBpcre_exec()\fP. 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.
-.
-.
-.SH "INFORMATION ABOUT A PATTERN"
-.rs
-.sp
-.B int pcre_fullinfo(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP,"
-.ti +5n
-.B int \fIwhat\fP, void *\fIwhere\fP);
-.PP
-The \fBpcre_fullinfo()\fP function returns information about a compiled
-pattern. It replaces the obsolete \fBpcre_info()\fP function, which is
-nevertheless retained for backwards compability (and is documented below).
-.P
-The first argument for \fBpcre_fullinfo()\fP is a pointer to the compiled
-pattern. The second argument is the result of \fBpcre_study()\fP, 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:
-.sp
-  PCRE_ERROR_NULL       the argument \fIcode\fP was NULL
-                        the argument \fIwhere\fP was NULL
-  PCRE_ERROR_BADMAGIC   the "magic number" was not found
-  PCRE_ERROR_BADOPTION  the value of \fIwhat\fP was invalid
-.sp
-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
-\fBpcre_fullinfo()\fP, to obtain the length of the compiled pattern:
-.sp
-  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 */
-.sp
-The possible values for the third argument are defined in \fBpcre.h\fP, and are
-as follows:
-.sp
-  PCRE_INFO_BACKREFMAX
-.sp
-Return the number of the highest back reference in the pattern. The fourth
-argument should point to an \fBint\fP variable. Zero is returned if there are
-no back references.
-.sp
-  PCRE_INFO_CAPTURECOUNT
-.sp
-Return the number of capturing subpatterns in the pattern. The fourth argument
-should point to an \fBint\fP variable.
-.sp
-  PCRE_INFO_DEFAULTTABLES
-.sp
-Return a pointer to the internal default character tables within PCRE. The
-fourth argument should point to an \fBunsigned char *\fP variable. This
-information call is provided for internal use by the \fBpcre_study()\fP
-function. External callers can cause PCRE to use its internal tables by passing
-a NULL table pointer.
-.sp
-  PCRE_INFO_FIRSTBYTE
-.sp
-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
-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 \fIwhere\fP.
-Otherwise, if either
-.sp
-(a) the pattern was compiled with the PCRE_MULTILINE option, and every branch
-starts with "^", or
-.sp
-(b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not set
-(if it were set, the pattern would be anchored),
-.sp
--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.
-.sp
-  PCRE_INFO_FIRSTTABLE
-.sp
-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 \fBunsigned char *\fP variable.
-.sp
-  PCRE_INFO_LASTLITERAL
-.sp
-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 \fBint\fP 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\ed+z\ed+/ the returned value is "z", but for /^a\edz\ed/ the returned value
-is -1.
-.sp
-  PCRE_INFO_NAMECOUNT
-  PCRE_INFO_NAMEENTRYSIZE
-  PCRE_INFO_NAMETABLE
-.sp
-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 \fBpcre_get_named_substring()\fP
-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
-\fBpcre_exec()\fP below). To do the conversion, you need to use the
-name-to-number map, which is described by these three values.
-.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 \fBint\fP 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 \fBchar\fP). 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):
-.sp
-.\" JOIN
-  (?P<date> (?P<year>(\ed\ed)?\ed\ed) -
-  (?P<month>\ed\ed) - (?P<day>\ed\ed) )
-.sp
-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 ??:
-.sp
-  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 ??
-.sp
-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.
-.sp
-  PCRE_INFO_OPTIONS
-.sp
-Return a copy of the options with which the pattern was compiled. The fourth
-argument should point to an \fBunsigned long int\fP variable. These option bits
-are those specified in the call to \fBpcre_compile()\fP, modified by any
-top-level option settings within the pattern itself.
-.P
-A pattern is automatically anchored by PCRE if all of its top-level
-alternatives begin with one of the following:
-.sp
-  ^     unless PCRE_MULTILINE is set
-  \eA    always
-  \eG    always
-.\" JOIN
-  .*    if PCRE_DOTALL is set and there are no back
-          references to the subpattern in which .* appears
-.sp
-For such patterns, the PCRE_ANCHORED bit is set in the options returned by
-\fBpcre_fullinfo()\fP.
-.sp
-  PCRE_INFO_SIZE
-.sp
-Return the size of the compiled pattern, that is, the value that was passed as
-the argument to \fBpcre_malloc()\fP when PCRE was getting memory in which to
-place the compiled data. The fourth argument should point to a \fBsize_t\fP
-variable.
-.sp
-  PCRE_INFO_STUDYSIZE
-.sp
-Return the size of the data block pointed to by the \fIstudy_data\fP field in
-a \fBpcre_extra\fP block. That is, it is the value that was passed to
-\fBpcre_malloc()\fP when PCRE was getting memory into which to place the data
-created by \fBpcre_study()\fP. The fourth argument should point to a
-\fBsize_t\fP variable.
-.
-.
-.SH "OBSOLETE INFO FUNCTION"
-.rs
-.sp
-.B int pcre_info(const pcre *\fIcode\fP, int *\fIoptptr\fP, int
-.B *\fIfirstcharptr\fP);
-.PP
-The \fBpcre_info()\fP function is now obsolete because its interface is too
-restrictive to return all the available data about a compiled pattern. New
-programs should use \fBpcre_fullinfo()\fP instead. The yield of
-\fBpcre_info()\fP is the number of capturing subpatterns, or one of the
-following negative numbers:
-.sp
-  PCRE_ERROR_NULL       the argument \fIcode\fP was NULL
-  PCRE_ERROR_BADMAGIC   the "magic number" was not found
-.sp
-If the \fIoptptr\fP 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
-If the pattern is not anchored and the \fIfirstcharptr\fP argument is not NULL,
-it is used to pass back information about the first character of any matched
-string (see PCRE_INFO_FIRSTBYTE above).
-.
-.
-.SH "MATCHING A PATTERN"
-.rs
-.sp
-.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);
-.P
-The function \fBpcre_exec()\fP is called to match a subject string against a
-compiled pattern, which is passed in the \fIcode\fP argument. If the
-pattern has been studied, the result of the study should be passed in the
-\fIextra\fP argument.
-.P
-In most applications, the pattern will have been compiled (and optionally
-studied) in the same process that calls \fBpcre_exec()\fP. 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
-.\" HREF
-\fBpcreprecompile\fP
-.\"
-documentation.
-.P
-Here is an example of a simple call to \fBpcre_exec()\fP:
-.sp
-  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) */
-.
-.\" HTML <a name="extradata"></a>
-.SS "Extra data for \fBpcre_exec()\fR"
-.rs
-.sp
-If the \fIextra\fP argument is not NULL, it must point to a \fBpcre_extra\fP
-data block. The \fBpcre_study()\fP 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 \fBpcre_extra\fP block are as
-follows:
-.sp
-  unsigned long int \fIflags\fP;
-  void *\fIstudy_data\fP;
-  unsigned long int \fImatch_limit\fP;
-  void *\fIcallout_data\fP;
-  const unsigned char *\fItables\fP;
-.sp
-The \fIflags\fP field is a bitmap that specifies which of the other fields
-are set. The flag bits are:
-.sp
-  PCRE_EXTRA_STUDY_DATA
-  PCRE_EXTRA_MATCH_LIMIT
-  PCRE_EXTRA_CALLOUT_DATA
-  PCRE_EXTRA_TABLES
-.sp
-Other flag bits should be set to zero. The \fIstudy_data\fP field is set in the
-\fBpcre_extra\fP block that is returned by \fBpcre_study()\fP, 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
-The \fImatch_limit\fP 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
-Internally, PCRE uses a function called \fBmatch()\fP 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
-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 \fBpcre_exec()\fP with a \fBpcre_extra\fP block
-in which \fImatch_limit\fP is set to a smaller value, and
-PCRE_EXTRA_MATCH_LIMIT is set in the \fIflags\fP field. If the limit is
-exceeded, \fBpcre_exec()\fP returns PCRE_ERROR_MATCHLIMIT.
-.P
-The \fIpcre_callout\fP field is used in conjunction with the "callout" feature,
-which is described in the
-.\" HREF
-\fBpcrecallout\fP
-.\"
-documentation.
-.P
-The \fItables\fP field is used to pass a character tables pointer to
-\fBpcre_exec()\fP; 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 \fBpcre_compile()\fP via its \fItableptr\fP argument.
-If NULL is passed to \fBpcre_exec()\fP 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 \fBpcre_exec()\fP is
-called. See the
-.\" HREF
-\fBpcreprecompile\fP
-.\"
-documentation for a discussion of saving compiled patterns for later use.
-.
-.SS "Option bits for \fBpcre_exec()\fP"
-.rs
-.sp
-The unused bits of the \fIoptions\fP argument for \fBpcre_exec()\fP 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.
-.sp
-  PCRE_ANCHORED
-.sp
-The PCRE_ANCHORED option limits \fBpcre_exec()\fP 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.
-.sp
-  PCRE_NOTBOL
-.sp
-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 \eA.
-.sp
-  PCRE_NOTEOL
-.sp
-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 \eZ or \ez.
-.sp
-  PCRE_NOTEMPTY
-.sp
-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
-.sp
-  a?b?
-.sp
-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
-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 \fBsplit()\fP 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 \fIpcredemo.c\fP sample program.
-.sp
-  PCRE_NO_UTF8_CHECK
-.sp
-When PCRE_UTF8 is set at compile time, the validity of the subject as a UTF-8
-string is automatically checked when \fBpcre_exec()\fP is subsequently called.
-The value of \fIstartoffset\fP 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,
-\fBpcre_exec()\fP returns the error PCRE_ERROR_BADUTF8. If \fIstartoffset\fP
-contains an invalid value, PCRE_ERROR_BADUTF8_OFFSET is returned.
-.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 \fBpcre_exec()\fP. You might want to do this for the second and
-subsequent calls to \fBpcre_exec()\fP 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 \fIstartoffset\fP 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 \fIstartoffset\fP that does not point to the start of a
-UTF-8 character, is undefined. Your program may crash.
-.sp
-  PCRE_PARTIAL
-.sp
-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), \fBpcre_exec()\fP 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
-.\" HREF
-\fBpcrepartial\fP
-.\"
-documentation.
-.
-.SS "The string to be matched by \fBpcre_exec()\fP"
-.rs
-.sp
-The subject string is passed to \fBpcre_exec()\fP as a pointer in
-\fIsubject\fP, a length in \fIlength\fP, and a starting byte offset in
-\fIstartoffset\fP. 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
-A non-zero starting offset is useful when searching for another match in the
-same subject by calling \fBpcre_exec()\fP again after a previous success.
-Setting \fIstartoffset\fP 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
-.sp
-  \eBiss\eB
-.sp
-which finds occurrences of "iss" in the middle of words. (\eB matches only if
-the current position in the subject is not a word boundary.) When applied to
-the string "Mississipi" the first call to \fBpcre_exec()\fP finds the first
-occurrence. If \fBpcre_exec()\fP is called again with just the remainder of the
-subject, namely "issipi", it does not match, because \eB is always false at the
-start of the subject, which is deemed to be a word boundary. However, if
-\fBpcre_exec()\fP is passed the entire string again, but with \fIstartoffset\fP
-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
-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.
-.
-.SS "How \fBpcre_exec()\fP returns captured substrings"
-.rs
-.sp
-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
-Captured substrings are returned to the caller via a vector of integer offsets
-whose address is passed in \fIovector\fP. The number of elements in the vector
-is passed in \fIovecsize\fP, which must be a non-negative number. \fBNote\fP:
-this argument is NOT the size of \fIovector\fP in bytes.
-.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 \fBpcre_exec()\fP while matching capturing subpatterns,
-and is not available for passing back information. The length passed in
-\fIovecsize\fP should always be a multiple of three. If it is not, it is
-rounded down.
-.P
-When a match is successful, information about captured substrings is returned
-in pairs of integers, starting at the beginning of \fIovector\fP, 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, \fIovector[0]\fP and \fIovector[1]\fP, 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 \fBpcre_exec()\fP
-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
-Some convenience functions are provided for extracting the captured substrings
-as separate strings. These are described in the following section.
-.P
-It is possible for an capturing subpattern number \fIn+1\fP to match some
-part of the subject when subpattern \fIn\fP 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
-If a capturing subpattern is matched repeatedly, it is the last portion of the
-string that it matched that is returned.
-.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, \fBpcre_exec()\fP may be called with \fIovector\fP passed as NULL and
-\fIovecsize\fP as zero. However, if the pattern contains back references and
-the \fIovector\fP 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 \fIovector\fP.
-.P
-Note that \fBpcre_info()\fP can be used to find out how many capturing
-subpatterns there are in a compiled pattern. The smallest size for
-\fIovector\fP that will allow for \fIn\fP captured substrings, in addition to
-the offsets of the substring matched by the whole pattern, is (\fIn\fP+1)*3.
-.
-.SS "Return values from \fBpcre_exec()\fP"
-.rs
-.sp
-If \fBpcre_exec()\fP fails, it returns a negative number. The following are
-defined in the header file:
-.sp
-  PCRE_ERROR_NOMATCH        (-1)
-.sp
-The subject string did not match the pattern.
-.sp
-  PCRE_ERROR_NULL           (-2)
-.sp
-Either \fIcode\fP or \fIsubject\fP was passed as NULL, or \fIovector\fP was
-NULL and \fIovecsize\fP was not zero.
-.sp
-  PCRE_ERROR_BADOPTION      (-3)
-.sp
-An unrecognized bit was set in the \fIoptions\fP argument.
-.sp
-  PCRE_ERROR_BADMAGIC       (-4)
-.sp
-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.
-.sp
-  PCRE_ERROR_UNKNOWN_NODE   (-5)
-.sp
-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.
-.sp
-  PCRE_ERROR_NOMEMORY       (-6)
-.sp
-If a pattern contains back references, but the \fIovector\fP that is passed to
-\fBpcre_exec()\fP 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 \fBpcre_malloc()\fP fails, this error is given. The memory is
-automatically freed at the end of matching.
-.sp
-  PCRE_ERROR_NOSUBSTRING    (-7)
-.sp
-This error is used by the \fBpcre_copy_substring()\fP,
-\fBpcre_get_substring()\fP, and \fBpcre_get_substring_list()\fP functions (see
-below). It is never returned by \fBpcre_exec()\fP.
-.sp
-  PCRE_ERROR_MATCHLIMIT     (-8)
-.sp
-The recursion and backtracking limit, as specified by the \fImatch_limit\fP
-field in a \fBpcre_extra\fP structure (or defaulted) was reached. See the
-description above.
-.sp
-  PCRE_ERROR_CALLOUT        (-9)
-.sp
-This error is never generated by \fBpcre_exec()\fP itself. It is provided for
-use by callout functions that want to yield a distinctive error code. See the
-.\" HREF
-\fBpcrecallout\fP
-.\"
-documentation for details.
-.sp
-  PCRE_ERROR_BADUTF8        (-10)
-.sp
-A string that contains an invalid UTF-8 byte sequence was passed as a subject.
-.sp
-  PCRE_ERROR_BADUTF8_OFFSET (-11)
-.sp
-The UTF-8 byte sequence that was passed as a subject was valid, but the value
-of \fIstartoffset\fP did not point to the beginning of a UTF-8 character.
-.sp
-  PCRE_ERROR_PARTIAL (-12)
-.sp
-The subject string did not match, but it did match partially. See the
-.\" HREF
-\fBpcrepartial\fP
-.\"
-documentation for details of partial matching.
-.sp
-  PCRE_ERROR_BAD_PARTIAL (-13)
-.sp
-The PCRE_PARTIAL option was used with a compiled pattern containing items that
-are not supported for partial matching. See the
-.\" HREF
-\fBpcrepartial\fP
-.\"
-documentation for details of partial matching.
-.sp
-  PCRE_ERROR_INTERNAL (-14)
-.sp
-An unexpected internal error has occurred. This error could be caused by a bug
-in PCRE or by overwriting of the compiled pattern.
-.sp
-  PCRE_ERROR_BADCOUNT (-15)
-.sp
-This error is given if the value of the \fIovecsize\fP argument is negative.
-.
-.
-.SH "EXTRACTING CAPTURED SUBSTRINGS BY NUMBER"
-.rs
-.sp
-.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
-.br
-.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
-.br
-.B int pcre_get_substring_list(const char *\fIsubject\fP,
-.ti +5n
-.B int *\fIovector\fP, int \fIstringcount\fP, "const char ***\fIlistptr\fP);"
-.PP
-Captured substrings can be accessed directly by using the offsets returned by
-\fBpcre_exec()\fP in \fIovector\fP. For convenience, the functions
-\fBpcre_copy_substring()\fP, \fBpcre_get_substring()\fP, and
-\fBpcre_get_substring_list()\fP 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
-The first three arguments are the same for all three of these functions:
-\fIsubject\fP is the subject string that has just been successfully matched,
-\fIovector\fP is a pointer to the vector of integer offsets that was passed to
-\fBpcre_exec()\fP, and \fIstringcount\fP 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 \fBpcre_exec()\fP if it is greater
-than zero. If \fBpcre_exec()\fP returned zero, indicating that it ran out of
-space in \fIovector\fP, the value passed as \fIstringcount\fP should be the
-number of elements in the vector divided by three.
-.P
-The functions \fBpcre_copy_substring()\fP and \fBpcre_get_substring()\fP
-extract a single substring, whose number is given as \fIstringnumber\fP. A
-value of zero extracts the substring that matched the entire pattern, whereas
-higher values extract the captured substrings. For \fBpcre_copy_substring()\fP,
-the string is placed in \fIbuffer\fP, whose length is given by
-\fIbuffersize\fP, while for \fBpcre_get_substring()\fP a new block of memory is
-obtained via \fBpcre_malloc\fP, and its address is returned via
-\fIstringptr\fP. The yield of the function is the length of the string, not
-including the terminating zero, or one of
-.sp
-  PCRE_ERROR_NOMEMORY       (-6)
-.sp
-The buffer was too small for \fBpcre_copy_substring()\fP, or the attempt to get
-memory failed for \fBpcre_get_substring()\fP.
-.sp
-  PCRE_ERROR_NOSUBSTRING    (-7)
-.sp
-There is no substring whose number is \fIstringnumber\fP.
-.P
-The \fBpcre_get_substring_list()\fP 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 \fBpcre_malloc\fP. The address of the memory block
-is returned via \fIlistptr\fP, 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
-.sp
-  PCRE_ERROR_NOMEMORY       (-6)
-.sp
-if the attempt to get the memory block failed.
-.P
-When any of these functions encounter a substring that is unset, which can
-happen when capturing subpattern number \fIn+1\fP matches some part of the
-subject, but subpattern \fIn\fP has not been used at all, they return an empty
-string. This can be distinguished from a genuine zero-length substring by
-inspecting the appropriate offset in \fIovector\fP, which is negative for unset
-substrings.
-.P
-The two convenience functions \fBpcre_free_substring()\fP and
-\fBpcre_free_substring_list()\fP can be used to free the memory returned by
-a previous call of \fBpcre_get_substring()\fP or
-\fBpcre_get_substring_list()\fP, respectively. They do nothing more than call
-the function pointed to by \fBpcre_free\fP, 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
-\fBpcre_free\fP directly; it is for these cases that the functions are
-provided.
-.
-.
-.SH "EXTRACTING CAPTURED SUBSTRINGS BY NAME"
-.rs
-.sp
-.B int pcre_get_stringnumber(const pcre *\fIcode\fP,
-.ti +5n
-.B const char *\fIname\fP);
-.PP
-.br
-.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
-.br
-.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
-To extract a substring by name, you first have to find associated number.
-For example, for this pattern
-.sp
-  (a+)b(?<xxx>\ed+)...
-.sp
-the number of the subpattern called "xxx" is 2. You can find the number from
-the name by calling \fBpcre_get_stringnumber()\fP. 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
-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
-Most of the arguments of \fIpcre_copy_named_substring()\fP and
-\fIpcre_get_named_substring()\fP 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
-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
-These functions call \fBpcre_get_stringnumber()\fP, and if it succeeds, they
-then call \fIpcre_copy_substring()\fP or \fIpcre_get_substring()\fP, as
-appropriate.
-.P
-.in 0
-Last updated: 09 September 2004
-.br
-Copyright (c) 1997-2004 University of Cambridge.