1 .TH PCREAPI 3

     2 .SH NAME

     3 PCRE - Perl-compatible regular expressions

     4 .SH "PCRE NATIVE API"

     5 .rs

     6 .sp

     7 .B #include <pcre.h>

     8 .PP

     9 .SM

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

    11 .ti +5n

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

    13 .ti +5n

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

    15 .PP

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

    17 .ti +5n

    18 .B int *\fIerrorcodeptr\fP,

    19 .ti +5n

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

    21 .ti +5n

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

    23 .PP

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

    25 .ti +5n

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

    27 .PP

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

    29 .ti +5n

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

    31 .ti +5n

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

    33 .PP

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

    35 .ti +5n

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

    37 .ti +5n

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

    39 .ti +5n

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

    41 .PP

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

    43 .ti +5n

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

    45 .ti +5n

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

    47 .ti +5n

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

    49 .PP

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

    51 .ti +5n

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

    53 .ti +5n

    54 .B int \fIbuffersize\fP);

    55 .PP

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

    57 .ti +5n

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

    59 .ti +5n

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

    61 .ti +5n

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

    63 .PP

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

    65 .ti +5n

    66 .B const char *\fIname\fP);

    67 .PP

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

    69 .ti +5n

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

    71 .PP

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

    73 .ti +5n

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

    75 .ti +5n

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

    77 .PP

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

    79 .ti +5n

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

    81 .PP

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

    83 .PP

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

    85 .PP

    86 .B const unsigned char *pcre_maketables(void);

    87 .PP

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

    89 .ti +5n

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

    91 .PP

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

    93 .B *\fIfirstcharptr\fP);

    94 .PP

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

    96 .PP

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

    98 .PP

    99 .B char *pcre_version(void);

   100 .PP

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

   102 .PP

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

   104 .PP

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

   106 .PP

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

   108 .PP

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

   110 .

   111 .

   112 .SH "PCRE API OVERVIEW"

   113 .rs

   114 .sp

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

   116 also some wrapper functions that correspond to the POSIX regular expression

   117 API. These are described in the

   118 .\" HREF

   119 \fBpcreposix\fP

   120 .\"

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

   122 wrapper is distributed with PCRE. It is documented in the

   123 .\" HREF

   124 \fBpcrecpp\fP

   125 .\"

   126 page.

   127 .P

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

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

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

   131 an application that uses PCRE. The header file defines the macros PCRE_MAJOR

   132 and PCRE_MINOR to contain the major and minor release numbers for the library.

   133 Applications can use these to include support for different releases of PCRE.

   134 .P

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

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

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

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

   139 distribution. The

   140 .\" HREF

   141 \fBpcresample\fP

   142 .\"

   143 documentation describes how to compile and run it.

   144 .P

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

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

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

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

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

   150 algorithms and their advantages and disadvantages is given in the

   151 .\" HREF

   152 \fBpcrematching\fP

   153 .\"

   154 documentation.

   155 .P

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

   157 functions for extracting captured substrings from a subject string that is

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

   159 .sp

   160   \fBpcre_copy_substring()\fP

   161   \fBpcre_copy_named_substring()\fP

   162   \fBpcre_get_substring()\fP

   163   \fBpcre_get_named_substring()\fP

   164   \fBpcre_get_substring_list()\fP

   165   \fBpcre_get_stringnumber()\fP

   166   \fBpcre_get_stringtable_entries()\fP

   167 .sp

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

   169 provided, to free the memory used for extracted strings.

   170 .P

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

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

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

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

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

   176 .P

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

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

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

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

   181 version of PCRE and its date of release.

   182 .P

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

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

   185 object-oriented applications.

   186 .P

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

   188 the entry points of the standard \fBmalloc()\fP and \fBfree()\fP functions,

   189 respectively. PCRE calls the memory management functions via these variables,

   190 so a calling program can replace them if it wishes to intercept the calls. This

   191 should be done before calling any PCRE functions.

   192 .P

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

   194 indirections to memory management functions. These special functions are used

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

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

   197 .\" HREF

   198 \fBpcrebuild\fP

   199 .\"

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

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

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

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

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

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

   206 discussion about PCRE's stack usage in the

   207 .\" HREF

   208 \fBpcrestack\fP

   209 .\"

   210 documentation.

   211 .P

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

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

   214 points during a matching operation. Details are given in the

   215 .\" HREF

   216 \fBpcrecallout\fP

   217 .\"

   218 documentation.

   219 .

   220 .

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

   222 .SH NEWLINES

   223 .rs

   224 .sp

   225 PCRE supports five different conventions for indicating line breaks in

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

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

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

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

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

   231 (paragraph separator, U+2029).

   232 .P

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

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

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

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

   237 matched.

   238 .P

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

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

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

   242 .\" HREF

   243 \fBpcrepattern\fP

   244 .\"

   245 page for details of the special character sequences.

   246 .P

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

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

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

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

   251 recognized line ending sequence, the match position advancement for a

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

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

   254 .\" </a>

   255 section on \fBpcre_exec()\fP options

   256 .\"

   257 below.

   258 .P

   259 The choice of newline convention does not affect the interpretation of

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

   261 controlled in a similar way, but by separate options.

   262 .

   263 .

   264 .SH MULTITHREADING

   265 .rs

   266 .sp

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

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

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

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

   271 .P

   272 The compiled form of a regular expression is not altered during matching, so

   273 the same compiled pattern can safely be used by several threads at once.

   274 .

   275 .

   276 .SH "SAVING PRECOMPILED PATTERNS FOR LATER USE"

   277 .rs

   278 .sp

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

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

   281 which it was compiled. Details are given in the

   282 .\" HREF

   283 \fBpcreprecompile\fP

   284 .\"

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

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

   287 crashes.

   288 .

   289 .

   290 .SH "CHECKING BUILD-TIME OPTIONS"

   291 .rs

   292 .sp

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

   294 .PP

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

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

   297 .\" HREF

   298 \fBpcrebuild\fP

   299 .\"

   300 documentation has more details about these optional features.

   301 .P

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

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

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

   305 .sp

   306   PCRE_CONFIG_UTF8

   307 .sp

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

   309 otherwise it is set to zero.

   310 .sp

   311   PCRE_CONFIG_UNICODE_PROPERTIES

   312 .sp

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

   314 properties is available; otherwise it is set to zero.

   315 .sp

   316   PCRE_CONFIG_NEWLINE

   317 .sp

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

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

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

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

   322 .sp

   323   PCRE_CONFIG_BSR

   324 .sp

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

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

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

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

   329 .sp

   330   PCRE_CONFIG_LINK_SIZE

   331 .sp

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

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

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

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

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

   337 .sp

   338   PCRE_CONFIG_POSIX_MALLOC_THRESHOLD

   339 .sp

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

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

   342 the

   343 .\" HREF

   344 \fBpcreposix\fP

   345 .\"

   346 documentation.

   347 .sp

   348   PCRE_CONFIG_MATCH_LIMIT

   349 .sp

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

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

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

   353 .sp

   354   PCRE_CONFIG_MATCH_LIMIT_RECURSION

   355 .sp

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

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

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

   359 .sp

   360   PCRE_CONFIG_STACKRECURSE

   361 .sp

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

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

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

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

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

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

   368 avoiding the use of the stack.

   369 .

   370 .

   371 .SH "COMPILING A PATTERN"

   372 .rs

   373 .sp

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

   375 .ti +5n

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

   377 .ti +5n

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

   379 .sp

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

   381 .ti +5n

   382 .B int *\fIerrorcodeptr\fP,

   383 .ti +5n

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

   385 .ti +5n

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

   387 .P

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

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

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

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

   392 .P

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

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

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

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

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

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

   399 .P

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

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

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

   403 argument, which is an address (see below).

   404 .P

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

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

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

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

   409 the detailed description in the

   410 .\" HREF

   411 \fBpcrepattern\fP

   412 .\"

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

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

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

   416 matching as well as at compile time.

   417 .P

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

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

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

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

   422 not try to free it. The offset from the start of the pattern to the character

   423 where the error was discovered is placed in the variable pointed to by

   424 \fIerroffset\fP, which must not be NULL. If it is, an immediate error is given.

   425 .P

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

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

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

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

   430 .P

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

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

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

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

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

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

   437 .P

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

   439 .sp

   440   pcre *re;

   441   const char *error;

   442   int erroffset;

   443   re = pcre_compile(

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

   445     0,                /* default options */

   446     &error,           /* for error message */

   447     &erroffset,       /* for error offset */

   448     NULL);            /* use default character tables */

   449 .sp

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

   451 file:

   452 .sp

   453   PCRE_ANCHORED

   454 .sp

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

   456 constrained to match only at the first matching point in the string that is

   457 being searched (the "subject string"). This effect can also be achieved by

   458 appropriate constructs in the pattern itself, which is the only way to do it in

   459 Perl.

   460 .sp

   461   PCRE_AUTO_CALLOUT

   462 .sp

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

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

   465 facility, see the

   466 .\" HREF

   467 \fBpcrecallout\fP

   468 .\"

   469 documentation.

   470 .sp

   471   PCRE_BSR_ANYCRLF

   472   PCRE_BSR_UNICODE

   473 .sp

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

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

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

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

   478 when a compiled pattern is matched.

   479 .sp

   480   PCRE_CASELESS

   481 .sp

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

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

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

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

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

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

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

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

   490 with UTF-8 support.

   491 .sp

   492   PCRE_DOLLAR_ENDONLY

   493 .sp

   494 If this bit is set, a dollar metacharacter in the pattern matches only at the

   495 end of the subject string. Without this option, a dollar also matches

   496 immediately before a newline at the end of the string (but not before any other

   497 newlines). The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is set.

   498 There is no equivalent to this option in Perl, and no way to set it within a

   499 pattern.

   500 .sp

   501   PCRE_DOTALL

   502 .sp

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

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

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

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

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

   508 the setting of this option.

   509 .sp

   510   PCRE_DUPNAMES

   511 .sp

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

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

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

   515 details of named subpatterns below; see also the

   516 .\" HREF

   517 \fBpcrepattern\fP

   518 .\"

   519 documentation.

   520 .sp

   521   PCRE_EXTENDED

   522 .sp

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

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

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

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

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

   528 pattern by a (?x) option setting.

   529 .P

   530 This option makes it possible to include comments inside complicated patterns.

   531 Note, however, that this applies only to data characters. Whitespace characters

   532 may never appear within special character sequences in a pattern, for example

   533 within the sequence (?( which introduces a conditional subpattern.

   534 .sp

   535   PCRE_EXTRA

   536 .sp

   537 This option was invented in order to turn on additional functionality of PCRE

   538 that is incompatible with Perl, but it is currently of very little use. When

   539 set, any backslash in a pattern that is followed by a letter that has no

   540 special meaning causes an error, thus reserving these combinations for future

   541 expansion. By default, as in Perl, a backslash followed by a letter with no

   542 special meaning is treated as a literal. (Perl can, however, be persuaded to

   543 give a warning for this.) There are at present no other features controlled by

   544 this option. It can also be set by a (?X) option setting within a pattern.

   545 .sp

   546   PCRE_FIRSTLINE

   547 .sp

   548 If this option is set, an unanchored pattern is required to match before or at

   549 the first newline in the subject string, though the matched text may continue

   550 over the newline.

   551 .sp

   552   PCRE_JAVASCRIPT_COMPAT

   553 .sp

   554 If this option is set, PCRE's behaviour is changed in some ways so that it is

   555 compatible with JavaScript rather than Perl. The changes are as follows:

   556 .P

   557 (1) A lone closing square bracket in a pattern causes a compile-time error,

   558 because this is illegal in JavaScript (by default it is treated as a data

   559 character). Thus, the pattern AB]CD becomes illegal when this option is set.

   560 .P

   561 (2) At run time, a back reference to an unset subpattern group matches an empty

   562 string (by default this causes the current matching alternative to fail). A

   563 pattern such as (\e1)(a) succeeds when this option is set (assuming it can find

   564 an "a" in the subject), whereas it fails by default, for Perl compatibility.

   565 .sp

   566   PCRE_MULTILINE

   567 .sp

   568 By default, PCRE treats the subject string as consisting of a single line of

   569 characters (even if it actually contains newlines). The "start of line"

   570 metacharacter (^) matches only at the start of the string, while the "end of

   571 line" metacharacter ($) matches only at the end of the string, or before a

   572 terminating newline (unless PCRE_DOLLAR_ENDONLY is set). This is the same as

   573 Perl.

   574 .P

   575 When PCRE_MULTILINE it is set, the "start of line" and "end of line" constructs

   576 match immediately following or immediately before internal newlines in the

   577 subject string, respectively, as well as at the very start and end. This is

   578 equivalent to Perl's /m option, and it can be changed within a pattern by a

   579 (?m) option setting. If there are no newlines in a subject string, or no

   580 occurrences of ^ or $ in a pattern, setting PCRE_MULTILINE has no effect.

   581 .sp

   582   PCRE_NEWLINE_CR

   583   PCRE_NEWLINE_LF

   584   PCRE_NEWLINE_CRLF

   585   PCRE_NEWLINE_ANYCRLF

   586   PCRE_NEWLINE_ANY

   587 .sp

   588 These options override the default newline definition that was chosen when PCRE

   589 was built. Setting the first or the second specifies that a newline is

   590 indicated by a single character (CR or LF, respectively). Setting

   591 PCRE_NEWLINE_CRLF specifies that a newline is indicated by the two-character

   592 CRLF sequence. Setting PCRE_NEWLINE_ANYCRLF specifies that any of the three

   593 preceding sequences should be recognized. Setting PCRE_NEWLINE_ANY specifies

   594 that any Unicode newline sequence should be recognized. The Unicode newline

   595 sequences are the three just mentioned, plus the single characters VT (vertical

   596 tab, U+000B), FF (formfeed, U+000C), NEL (next line, U+0085), LS (line

   597 separator, U+2028), and PS (paragraph separator, U+2029). The last two are

   598 recognized only in UTF-8 mode.

   599 .P

   600 The newline setting in the options word uses three bits that are treated

   601 as a number, giving eight possibilities. Currently only six are used (default

   602 plus the five values above). This means that if you set more than one newline

   603 option, the combination may or may not be sensible. For example,

   604 PCRE_NEWLINE_CR with PCRE_NEWLINE_LF is equivalent to PCRE_NEWLINE_CRLF, but

   605 other combinations may yield unused numbers and cause an error.

   606 .P

   607 The only time that a line break is specially recognized when compiling a

   608 pattern is if PCRE_EXTENDED is set, and an unescaped # outside a character

   609 class is encountered. This indicates a comment that lasts until after the next

   610 line break sequence. In other circumstances, line break sequences are treated

   611 as literal data, except that in PCRE_EXTENDED mode, both CR and LF are treated

   612 as whitespace characters and are therefore ignored.

   613 .P

   614 The newline option that is set at compile time becomes the default that is used

   615 for \fBpcre_exec()\fP and \fBpcre_dfa_exec()\fP, but it can be overridden.

   616 .sp

   617   PCRE_NO_AUTO_CAPTURE

   618 .sp

   619 If this option is set, it disables the use of numbered capturing parentheses in

   620 the pattern. Any opening parenthesis that is not followed by ? behaves as if it

   621 were followed by ?: but named parentheses can still be used for capturing (and

   622 they acquire numbers in the usual way). There is no equivalent of this option

   623 in Perl.

   624 .sp

   625   PCRE_UNGREEDY

   626 .sp

   627 This option inverts the "greediness" of the quantifiers so that they are not

   628 greedy by default, but become greedy if followed by "?". It is not compatible

   629 with Perl. It can also be set by a (?U) option setting within the pattern.

   630 .sp

   631   PCRE_UTF8

   632 .sp

   633 This option causes PCRE to regard both the pattern and the subject as strings

   634 of UTF-8 characters instead of single-byte character strings. However, it is

   635 available only when PCRE is built to include UTF-8 support. If not, the use

   636 of this option provokes an error. Details of how this option changes the

   637 behaviour of PCRE are given in the

   638 .\" HTML <a href="pcre.html#utf8support">

   639 .\" </a>

   640 section on UTF-8 support

   641 .\"

   642 in the main

   643 .\" HREF

   644 \fBpcre\fP

   645 .\"

   646 page.

   647 .sp

   648   PCRE_NO_UTF8_CHECK

   649 .sp

   650 When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string is

   651 automatically checked. There is a discussion about the

   652 .\" HTML <a href="pcre.html#utf8strings">

   653 .\" </a>

   654 validity of UTF-8 strings

   655 .\"

   656 in the main

   657 .\" HREF

   658 \fBpcre\fP

   659 .\"

   660 page. If an invalid UTF-8 sequence of bytes is found, \fBpcre_compile()\fP

   661 returns an error. If you already know that your pattern is valid, and you want

   662 to skip this check for performance reasons, you can set the PCRE_NO_UTF8_CHECK

   663 option. When it is set, the effect of passing an invalid UTF-8 string as a

   664 pattern is undefined. It may cause your program to crash. Note that this option

   665 can also be passed to \fBpcre_exec()\fP and \fBpcre_dfa_exec()\fP, to suppress

   666 the UTF-8 validity checking of subject strings.

   667 .

   668 .

   669 .SH "COMPILATION ERROR CODES"

   670 .rs

   671 .sp

   672 The following table lists the error codes than may be returned by

   673 \fBpcre_compile2()\fP, along with the error messages that may be returned by

   674 both compiling functions. As PCRE has developed, some error codes have fallen

   675 out of use. To avoid confusion, they have not been re-used.

   676 .sp

   677    0  no error

   678    1  \e at end of pattern

   679    2  \ec at end of pattern

   680    3  unrecognized character follows \e

   681    4  numbers out of order in {} quantifier

   682    5  number too big in {} quantifier

   683    6  missing terminating ] for character class

   684    7  invalid escape sequence in character class

   685    8  range out of order in character class

   686    9  nothing to repeat

   687   10  [this code is not in use]

   688   11  internal error: unexpected repeat

   689   12  unrecognized character after (? or (?-

   690   13  POSIX named classes are supported only within a class

   691   14  missing )

   692   15  reference to non-existent subpattern

   693   16  erroffset passed as NULL

   694   17  unknown option bit(s) set

   695   18  missing ) after comment

   696   19  [this code is not in use]

   697   20  regular expression is too large

   698   21  failed to get memory

   699   22  unmatched parentheses

   700   23  internal error: code overflow

   701   24  unrecognized character after (?<

   702   25  lookbehind assertion is not fixed length

   703   26  malformed number or name after (?(

   704   27  conditional group contains more than two branches

   705   28  assertion expected after (?(

   706   29  (?R or (?[+-]digits must be followed by )

   707   30  unknown POSIX class name

   708   31  POSIX collating elements are not supported

   709   32  this version of PCRE is not compiled with PCRE_UTF8 support

   710   33  [this code is not in use]

   711   34  character value in \ex{...} sequence is too large

   712   35  invalid condition (?(0)

   713   36  \eC not allowed in lookbehind assertion

   714   37  PCRE does not support \eL, \el, \eN, \eU, or \eu

   715   38  number after (?C is > 255

   716   39  closing ) for (?C expected

   717   40  recursive call could loop indefinitely

   718   41  unrecognized character after (?P

   719   42  syntax error in subpattern name (missing terminator)

   720   43  two named subpatterns have the same name

   721   44  invalid UTF-8 string

   722   45  support for \eP, \ep, and \eX has not been compiled

   723   46  malformed \eP or \ep sequence

   724   47  unknown property name after \eP or \ep

   725   48  subpattern name is too long (maximum 32 characters)

   726   49  too many named subpatterns (maximum 10000)

   727   50  [this code is not in use]

   728   51  octal value is greater than \e377 (not in UTF-8 mode)

   729   52  internal error: overran compiling workspace

   730   53  internal error: previously-checked referenced subpattern not found

   731   54  DEFINE group contains more than one branch

   732   55  repeating a DEFINE group is not allowed

   733   56  inconsistent NEWLINE options

   734   57  \eg is not followed by a braced, angle-bracketed, or quoted

   735         name/number or by a plain number

   736   58  a numbered reference must not be zero

   737   59  (*VERB) with an argument is not supported

   738   60  (*VERB) not recognized

   739   61  number is too big

   740   62  subpattern name expected

   741   63  digit expected after (?+

   742   64  ] is an invalid data character in JavaScript compatibility mode

   743 .sp

   744 The numbers 32 and 10000 in errors 48 and 49 are defaults; different values may

   745 be used if the limits were changed when PCRE was built.

   746 .

   747 .

   748 .SH "STUDYING A PATTERN"

   749 .rs

   750 .sp

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

   752 .ti +5n

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

   754 .PP

   755 If a compiled pattern is going to be used several times, it is worth spending

   756 more time analyzing it in order to speed up the time taken for matching. The

   757 function \fBpcre_study()\fP takes a pointer to a compiled pattern as its first

   758 argument. If studying the pattern produces additional information that will

   759 help speed up matching, \fBpcre_study()\fP returns a pointer to a

   760 \fBpcre_extra\fP block, in which the \fIstudy_data\fP field points to the

   761 results of the study.

   762 .P

   763 The returned value from \fBpcre_study()\fP can be passed directly to

   764 \fBpcre_exec()\fP. However, a \fBpcre_extra\fP block also contains other

   765 fields that can be set by the caller before the block is passed; these are

   766 described

   767 .\" HTML <a href="#extradata">

   768 .\" </a>

   769 below

   770 .\"

   771 in the section on matching a pattern.

   772 .P

   773 If studying the pattern does not produce any additional information

   774 \fBpcre_study()\fP returns NULL. In that circumstance, if the calling program

   775 wants to pass any of the other fields to \fBpcre_exec()\fP, it must set up its

   776 own \fBpcre_extra\fP block.

   777 .P

   778 The second argument of \fBpcre_study()\fP contains option bits. At present, no

   779 options are defined, and this argument should always be zero.

   780 .P

   781 The third argument for \fBpcre_study()\fP is a pointer for an error message. If

   782 studying succeeds (even if no data is returned), the variable it points to is

   783 set to NULL. Otherwise it is set to point to a textual error message. This is a

   784 static string that is part of the library. You must not try to free it. You

   785 should test the error pointer for NULL after calling \fBpcre_study()\fP, to be

   786 sure that it has run successfully.

   787 .P

   788 This is a typical call to \fBpcre_study\fP():

   789 .sp

   790   pcre_extra *pe;

   791   pe = pcre_study(

   792     re,             /* result of pcre_compile() */

   793     0,              /* no options exist */

   794     &error);        /* set to NULL or points to a message */

   795 .sp

   796 At present, studying a pattern is useful only for non-anchored patterns that do

   797 not have a single fixed starting character. A bitmap of possible starting

   798 bytes is created.

   799 .

   800 .

   801 .\" HTML <a name="localesupport"></a>

   802 .SH "LOCALE SUPPORT"

   803 .rs

   804 .sp

   805 PCRE handles caseless matching, and determines whether characters are letters,

   806 digits, or whatever, by reference to a set of tables, indexed by character

   807 value. When running in UTF-8 mode, this applies only to characters with codes

   808 less than 128. Higher-valued codes never match escapes such as \ew or \ed, but

   809 can be tested with \ep if PCRE is built with Unicode character property

   810 support. The use of locales with Unicode is discouraged. If you are handling

   811 characters with codes greater than 128, you should either use UTF-8 and

   812 Unicode, or use locales, but not try to mix the two.

   813 .P

   814 PCRE contains an internal set of tables that are used when the final argument

   815 of \fBpcre_compile()\fP is NULL. These are sufficient for many applications.

   816 Normally, the internal tables recognize only ASCII characters. However, when

   817 PCRE is built, it is possible to cause the internal tables to be rebuilt in the

   818 default "C" locale of the local system, which may cause them to be different.

   819 .P

   820 The internal tables can always be overridden by tables supplied by the

   821 application that calls PCRE. These may be created in a different locale from

   822 the default. As more and more applications change to using Unicode, the need

   823 for this locale support is expected to die away.

   824 .P

   825 External tables are built by calling the \fBpcre_maketables()\fP function,

   826 which has no arguments, in the relevant locale. The result can then be passed

   827 to \fBpcre_compile()\fP or \fBpcre_exec()\fP as often as necessary. For

   828 example, to build and use tables that are appropriate for the French locale

   829 (where accented characters with values greater than 128 are treated as letters),

   830 the following code could be used:

   831 .sp

   832   setlocale(LC_CTYPE, "fr_FR");

   833   tables = pcre_maketables();

   834   re = pcre_compile(..., tables);

   835 .sp

   836 The locale name "fr_FR" is used on Linux and other Unix-like systems; if you

   837 are using Windows, the name for the French locale is "french".

   838 .P

   839 When \fBpcre_maketables()\fP runs, the tables are built in memory that is

   840 obtained via \fBpcre_malloc\fP. It is the caller's responsibility to ensure

   841 that the memory containing the tables remains available for as long as it is

   842 needed.

   843 .P

   844 The pointer that is passed to \fBpcre_compile()\fP is saved with the compiled

   845 pattern, and the same tables are used via this pointer by \fBpcre_study()\fP

   846 and normally also by \fBpcre_exec()\fP. Thus, by default, for any single

   847 pattern, compilation, studying and matching all happen in the same locale, but

   848 different patterns can be compiled in different locales.

   849 .P

   850 It is possible to pass a table pointer or NULL (indicating the use of the

   851 internal tables) to \fBpcre_exec()\fP. Although not intended for this purpose,

   852 this facility could be used to match a pattern in a different locale from the

   853 one in which it was compiled. Passing table pointers at run time is discussed

   854 below in the section on matching a pattern.

   855 .

   856 .

   857 .SH "INFORMATION ABOUT A PATTERN"

   858 .rs

   859 .sp

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

   861 .ti +5n

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

   863 .PP

   864 The \fBpcre_fullinfo()\fP function returns information about a compiled

   865 pattern. It replaces the obsolete \fBpcre_info()\fP function, which is

   866 nevertheless retained for backwards compability (and is documented below).

   867 .P

   868 The first argument for \fBpcre_fullinfo()\fP is a pointer to the compiled

   869 pattern. The second argument is the result of \fBpcre_study()\fP, or NULL if

   870 the pattern was not studied. The third argument specifies which piece of

   871 information is required, and the fourth argument is a pointer to a variable

   872 to receive the data. The yield of the function is zero for success, or one of

   873 the following negative numbers:

   874 .sp

   875   PCRE_ERROR_NULL       the argument \fIcode\fP was NULL

   876                         the argument \fIwhere\fP was NULL

   877   PCRE_ERROR_BADMAGIC   the "magic number" was not found

   878   PCRE_ERROR_BADOPTION  the value of \fIwhat\fP was invalid

   879 .sp

   880 The "magic number" is placed at the start of each compiled pattern as an simple

   881 check against passing an arbitrary memory pointer. Here is a typical call of

   882 \fBpcre_fullinfo()\fP, to obtain the length of the compiled pattern:

   883 .sp

   884   int rc;

   885   size_t length;

   886   rc = pcre_fullinfo(

   887     re,               /* result of pcre_compile() */

   888     pe,               /* result of pcre_study(), or NULL */

   889     PCRE_INFO_SIZE,   /* what is required */

   890     &length);         /* where to put the data */

   891 .sp

   892 The possible values for the third argument are defined in \fBpcre.h\fP, and are

   893 as follows:

   894 .sp

   895   PCRE_INFO_BACKREFMAX

   896 .sp

   897 Return the number of the highest back reference in the pattern. The fourth

   898 argument should point to an \fBint\fP variable. Zero is returned if there are

   899 no back references.

   900 .sp

   901   PCRE_INFO_CAPTURECOUNT

   902 .sp

   903 Return the number of capturing subpatterns in the pattern. The fourth argument

   904 should point to an \fBint\fP variable.

   905 .sp

   906   PCRE_INFO_DEFAULT_TABLES

   907 .sp

   908 Return a pointer to the internal default character tables within PCRE. The

   909 fourth argument should point to an \fBunsigned char *\fP variable. This

   910 information call is provided for internal use by the \fBpcre_study()\fP

   911 function. External callers can cause PCRE to use its internal tables by passing

   912 a NULL table pointer.

   913 .sp

   914   PCRE_INFO_FIRSTBYTE

   915 .sp

   916 Return information about the first byte of any matched string, for a

   917 non-anchored pattern. The fourth argument should point to an \fBint\fP

   918 variable. (This option used to be called PCRE_INFO_FIRSTCHAR; the old name is

   919 still recognized for backwards compatibility.)

   920 .P

   921 If there is a fixed first byte, for example, from a pattern such as

   922 (cat|cow|coyote), its value is returned. Otherwise, if either

   923 .sp

   924 (a) the pattern was compiled with the PCRE_MULTILINE option, and every branch

   925 starts with "^", or

   926 .sp

   927 (b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not set

   928 (if it were set, the pattern would be anchored),

   929 .sp

   930 -1 is returned, indicating that the pattern matches only at the start of a

   931 subject string or after any newline within the string. Otherwise -2 is

   932 returned. For anchored patterns, -2 is returned.

   933 .sp

   934   PCRE_INFO_FIRSTTABLE

   935 .sp

   936 If the pattern was studied, and this resulted in the construction of a 256-bit

   937 table indicating a fixed set of bytes for the first byte in any matching

   938 string, a pointer to the table is returned. Otherwise NULL is returned. The

   939 fourth argument should point to an \fBunsigned char *\fP variable.

   940 .sp

   941   PCRE_INFO_HASCRORLF

   942 .sp

   943 Return 1 if the pattern contains any explicit matches for CR or LF characters,

   944 otherwise 0. The fourth argument should point to an \fBint\fP variable. An

   945 explicit match is either a literal CR or LF character, or \er or \en.

   946 .sp

   947   PCRE_INFO_JCHANGED

   948 .sp

   949 Return 1 if the (?J) or (?-J) option setting is used in the pattern, otherwise

   950 0. The fourth argument should point to an \fBint\fP variable. (?J) and

   951 (?-J) set and unset the local PCRE_DUPNAMES option, respectively.

   952 .sp

   953   PCRE_INFO_LASTLITERAL

   954 .sp

   955 Return the value of the rightmost literal byte that must exist in any matched

   956 string, other than at its start, if such a byte has been recorded. The fourth

   957 argument should point to an \fBint\fP variable. If there is no such byte, -1 is

   958 returned. For anchored patterns, a last literal byte is recorded only if it

   959 follows something of variable length. For example, for the pattern

   960 /^a\ed+z\ed+/ the returned value is "z", but for /^a\edz\ed/ the returned value

   961 is -1.

   962 .sp

   963   PCRE_INFO_NAMECOUNT

   964   PCRE_INFO_NAMEENTRYSIZE

   965   PCRE_INFO_NAMETABLE

   966 .sp

   967 PCRE supports the use of named as well as numbered capturing parentheses. The

   968 names are just an additional way of identifying the parentheses, which still

   969 acquire numbers. Several convenience functions such as

   970 \fBpcre_get_named_substring()\fP are provided for extracting captured

   971 substrings by name. It is also possible to extract the data directly, by first

   972 converting the name to a number in order to access the correct pointers in the

   973 output vector (described with \fBpcre_exec()\fP below). To do the conversion,

   974 you need to use the name-to-number map, which is described by these three

   975 values.

   976 .P

   977 The map consists of a number of fixed-size entries. PCRE_INFO_NAMECOUNT gives

   978 the number of entries, and PCRE_INFO_NAMEENTRYSIZE gives the size of each

   979 entry; both of these return an \fBint\fP value. The entry size depends on the

   980 length of the longest name. PCRE_INFO_NAMETABLE returns a pointer to the first

   981 entry of the table (a pointer to \fBchar\fP). The first two bytes of each entry

   982 are the number of the capturing parenthesis, most significant byte first. The

   983 rest of the entry is the corresponding name, zero terminated. The names are in

   984 alphabetical order. When PCRE_DUPNAMES is set, duplicate names are in order of

   985 their parentheses numbers. For example, consider the following pattern (assume

   986 PCRE_EXTENDED is set, so white space - including newlines - is ignored):

   987 .sp

   988 .\" JOIN

   989   (?<date> (?<year>(\ed\ed)?\ed\ed) -

   990   (?<month>\ed\ed) - (?<day>\ed\ed) )

   991 .sp

   992 There are four named subpatterns, so the table has four entries, and each entry

   993 in the table is eight bytes long. The table is as follows, with non-printing

   994 bytes shows in hexadecimal, and undefined bytes shown as ??:

   995 .sp

   996   00 01 d  a  t  e  00 ??

   997   00 05 d  a  y  00 ?? ??

   998   00 04 m  o  n  t  h  00

   999   00 02 y  e  a  r  00 ??

  1000 .sp

  1001 When writing code to extract data from named subpatterns using the

  1002 name-to-number map, remember that the length of the entries is likely to be

  1003 different for each compiled pattern.

  1004 .sp

  1005   PCRE_INFO_OKPARTIAL

  1006 .sp

  1007 Return 1 if the pattern can be used for partial matching, otherwise 0. The

  1008 fourth argument should point to an \fBint\fP variable. The

  1009 .\" HREF

  1010 \fBpcrepartial\fP

  1011 .\"

  1012 documentation lists the restrictions that apply to patterns when partial

  1013 matching is used.

  1014 .sp

  1015   PCRE_INFO_OPTIONS

  1016 .sp

  1017 Return a copy of the options with which the pattern was compiled. The fourth

  1018 argument should point to an \fBunsigned long int\fP variable. These option bits

  1019 are those specified in the call to \fBpcre_compile()\fP, modified by any

  1020 top-level option settings at the start of the pattern itself. In other words,

  1021 they are the options that will be in force when matching starts. For example,

  1022 if the pattern /(?im)abc(?-i)d/ is compiled with the PCRE_EXTENDED option, the

  1023 result is PCRE_CASELESS, PCRE_MULTILINE, and PCRE_EXTENDED.

  1024 .P

  1025 A pattern is automatically anchored by PCRE if all of its top-level

  1026 alternatives begin with one of the following:

  1027 .sp

  1028   ^     unless PCRE_MULTILINE is set

  1029   \eA    always

  1030   \eG    always

  1031 .\" JOIN

  1032   .*    if PCRE_DOTALL is set and there are no back

  1033           references to the subpattern in which .* appears

  1034 .sp

  1035 For such patterns, the PCRE_ANCHORED bit is set in the options returned by

  1036 \fBpcre_fullinfo()\fP.

  1037 .sp

  1038   PCRE_INFO_SIZE

  1039 .sp

  1040 Return the size of the compiled pattern, that is, the value that was passed as

  1041 the argument to \fBpcre_malloc()\fP when PCRE was getting memory in which to

  1042 place the compiled data. The fourth argument should point to a \fBsize_t\fP

  1043 variable.

  1044 .sp

  1045   PCRE_INFO_STUDYSIZE

  1046 .sp

  1047 Return the size of the data block pointed to by the \fIstudy_data\fP field in

  1048 a \fBpcre_extra\fP block. That is, it is the value that was passed to

  1049 \fBpcre_malloc()\fP when PCRE was getting memory into which to place the data

  1050 created by \fBpcre_study()\fP. The fourth argument should point to a

  1051 \fBsize_t\fP variable.

  1052 .

  1053 .

  1054 .SH "OBSOLETE INFO FUNCTION"

  1055 .rs

  1056 .sp

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

  1058 .B *\fIfirstcharptr\fP);

  1059 .PP

  1060 The \fBpcre_info()\fP function is now obsolete because its interface is too

  1061 restrictive to return all the available data about a compiled pattern. New

  1062 programs should use \fBpcre_fullinfo()\fP instead. The yield of

  1063 \fBpcre_info()\fP is the number of capturing subpatterns, or one of the

  1064 following negative numbers:

  1065 .sp

  1066   PCRE_ERROR_NULL       the argument \fIcode\fP was NULL

  1067   PCRE_ERROR_BADMAGIC   the "magic number" was not found

  1068 .sp

  1069 If the \fIoptptr\fP argument is not NULL, a copy of the options with which the

  1070 pattern was compiled is placed in the integer it points to (see

  1071 PCRE_INFO_OPTIONS above).

  1072 .P

  1073 If the pattern is not anchored and the \fIfirstcharptr\fP argument is not NULL,

  1074 it is used to pass back information about the first character of any matched

  1075 string (see PCRE_INFO_FIRSTBYTE above).

  1076 .

  1077 .

  1078 .SH "REFERENCE COUNTS"

  1079 .rs

  1080 .sp

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

  1082 .PP

  1083 The \fBpcre_refcount()\fP function is used to maintain a reference count in the

  1084 data block that contains a compiled pattern. It is provided for the benefit of

  1085 applications that operate in an object-oriented manner, where different parts

  1086 of the application may be using the same compiled pattern, but you want to free

  1087 the block when they are all done.

  1088 .P

  1089 When a pattern is compiled, the reference count field is initialized to zero.

  1090 It is changed only by calling this function, whose action is to add the

  1091 \fIadjust\fP value (which may be positive or negative) to it. The yield of the

  1092 function is the new value. However, the value of the count is constrained to

  1093 lie between 0 and 65535, inclusive. If the new value is outside these limits,

  1094 it is forced to the appropriate limit value.

  1095 .P

  1096 Except when it is zero, the reference count is not correctly preserved if a

  1097 pattern is compiled on one host and then transferred to a host whose byte-order

  1098 is different. (This seems a highly unlikely scenario.)

  1099 .

  1100 .

  1101 .SH "MATCHING A PATTERN: THE TRADITIONAL FUNCTION"

  1102 .rs

  1103 .sp

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

  1105 .ti +5n

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

  1107 .ti +5n

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

  1109 .P

  1110 The function \fBpcre_exec()\fP is called to match a subject string against a

  1111 compiled pattern, which is passed in the \fIcode\fP argument. If the

  1112 pattern has been studied, the result of the study should be passed in the

  1113 \fIextra\fP argument. This function is the main matching facility of the

  1114 library, and it operates in a Perl-like manner. For specialist use there is

  1115 also an alternative matching function, which is described

  1116 .\" HTML <a href="#dfamatch">

  1117 .\" </a>

  1118 below

  1119 .\"

  1120 in the section about the \fBpcre_dfa_exec()\fP function.

  1121 .P

  1122 In most applications, the pattern will have been compiled (and optionally

  1123 studied) in the same process that calls \fBpcre_exec()\fP. However, it is

  1124 possible to save compiled patterns and study data, and then use them later

  1125 in different processes, possibly even on different hosts. For a discussion

  1126 about this, see the

  1127 .\" HREF

  1128 \fBpcreprecompile\fP

  1129 .\"

  1130 documentation.

  1131 .P

  1132 Here is an example of a simple call to \fBpcre_exec()\fP:

  1133 .sp

  1134   int rc;

  1135   int ovector[30];