diff options
Diffstat (limited to 'srclib/pcre/doc/pcreapi.3')
| -rw-r--r-- | srclib/pcre/doc/pcreapi.3 | 1288 |
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. |