|
1 <html> |
|
2 <head> |
|
3 <title>pcreapi specification</title> |
|
4 </head> |
|
5 <body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB"> |
|
6 <h1>pcreapi man page</h1> |
|
7 <p> |
|
8 Return to the <a href="index.html">PCRE index page</a>. |
|
9 </p> |
|
10 <p> |
|
11 This page is part of the PCRE HTML documentation. It was generated automatically |
|
12 from the original man page. If there is any nonsense in it, please consult the |
|
13 man page, in case the conversion went wrong. |
|
14 <br> |
|
15 <ul> |
|
16 <li><a name="TOC1" href="#SEC1">PCRE NATIVE API</a> |
|
17 <li><a name="TOC2" href="#SEC2">PCRE API OVERVIEW</a> |
|
18 <li><a name="TOC3" href="#SEC3">NEWLINES</a> |
|
19 <li><a name="TOC4" href="#SEC4">MULTITHREADING</a> |
|
20 <li><a name="TOC5" href="#SEC5">SAVING PRECOMPILED PATTERNS FOR LATER USE</a> |
|
21 <li><a name="TOC6" href="#SEC6">CHECKING BUILD-TIME OPTIONS</a> |
|
22 <li><a name="TOC7" href="#SEC7">COMPILING A PATTERN</a> |
|
23 <li><a name="TOC8" href="#SEC8">COMPILATION ERROR CODES</a> |
|
24 <li><a name="TOC9" href="#SEC9">STUDYING A PATTERN</a> |
|
25 <li><a name="TOC10" href="#SEC10">LOCALE SUPPORT</a> |
|
26 <li><a name="TOC11" href="#SEC11">INFORMATION ABOUT A PATTERN</a> |
|
27 <li><a name="TOC12" href="#SEC12">OBSOLETE INFO FUNCTION</a> |
|
28 <li><a name="TOC13" href="#SEC13">REFERENCE COUNTS</a> |
|
29 <li><a name="TOC14" href="#SEC14">MATCHING A PATTERN: THE TRADITIONAL FUNCTION</a> |
|
30 <li><a name="TOC15" href="#SEC15">EXTRACTING CAPTURED SUBSTRINGS BY NUMBER</a> |
|
31 <li><a name="TOC16" href="#SEC16">EXTRACTING CAPTURED SUBSTRINGS BY NAME</a> |
|
32 <li><a name="TOC17" href="#SEC17">DUPLICATE SUBPATTERN NAMES</a> |
|
33 <li><a name="TOC18" href="#SEC18">FINDING ALL POSSIBLE MATCHES</a> |
|
34 <li><a name="TOC19" href="#SEC19">MATCHING A PATTERN: THE ALTERNATIVE FUNCTION</a> |
|
35 <li><a name="TOC20" href="#SEC20">SEE ALSO</a> |
|
36 <li><a name="TOC21" href="#SEC21">AUTHOR</a> |
|
37 <li><a name="TOC22" href="#SEC22">REVISION</a> |
|
38 </ul> |
|
39 <br><a name="SEC1" href="#TOC1">PCRE NATIVE API</a><br> |
|
40 <P> |
|
41 <b>#include <pcre.h></b> |
|
42 </P> |
|
43 <P> |
|
44 <b>pcre *pcre_compile(const char *<i>pattern</i>, int <i>options</i>,</b> |
|
45 <b>const char **<i>errptr</i>, int *<i>erroffset</i>,</b> |
|
46 <b>const unsigned char *<i>tableptr</i>);</b> |
|
47 </P> |
|
48 <P> |
|
49 <b>pcre *pcre_compile2(const char *<i>pattern</i>, int <i>options</i>,</b> |
|
50 <b>int *<i>errorcodeptr</i>,</b> |
|
51 <b>const char **<i>errptr</i>, int *<i>erroffset</i>,</b> |
|
52 <b>const unsigned char *<i>tableptr</i>);</b> |
|
53 </P> |
|
54 <P> |
|
55 <b>pcre_extra *pcre_study(const pcre *<i>code</i>, int <i>options</i>,</b> |
|
56 <b>const char **<i>errptr</i>);</b> |
|
57 </P> |
|
58 <P> |
|
59 <b>int pcre_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> |
|
60 <b>const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b> |
|
61 <b>int <i>options</i>, int *<i>ovector</i>, int <i>ovecsize</i>);</b> |
|
62 </P> |
|
63 <P> |
|
64 <b>int pcre_dfa_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> |
|
65 <b>const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b> |
|
66 <b>int <i>options</i>, int *<i>ovector</i>, int <i>ovecsize</i>,</b> |
|
67 <b>int *<i>workspace</i>, int <i>wscount</i>);</b> |
|
68 </P> |
|
69 <P> |
|
70 <b>int pcre_copy_named_substring(const pcre *<i>code</i>,</b> |
|
71 <b>const char *<i>subject</i>, int *<i>ovector</i>,</b> |
|
72 <b>int <i>stringcount</i>, const char *<i>stringname</i>,</b> |
|
73 <b>char *<i>buffer</i>, int <i>buffersize</i>);</b> |
|
74 </P> |
|
75 <P> |
|
76 <b>int pcre_copy_substring(const char *<i>subject</i>, int *<i>ovector</i>,</b> |
|
77 <b>int <i>stringcount</i>, int <i>stringnumber</i>, char *<i>buffer</i>,</b> |
|
78 <b>int <i>buffersize</i>);</b> |
|
79 </P> |
|
80 <P> |
|
81 <b>int pcre_get_named_substring(const pcre *<i>code</i>,</b> |
|
82 <b>const char *<i>subject</i>, int *<i>ovector</i>,</b> |
|
83 <b>int <i>stringcount</i>, const char *<i>stringname</i>,</b> |
|
84 <b>const char **<i>stringptr</i>);</b> |
|
85 </P> |
|
86 <P> |
|
87 <b>int pcre_get_stringnumber(const pcre *<i>code</i>,</b> |
|
88 <b>const char *<i>name</i>);</b> |
|
89 </P> |
|
90 <P> |
|
91 <b>int pcre_get_stringtable_entries(const pcre *<i>code</i>,</b> |
|
92 <b>const char *<i>name</i>, char **<i>first</i>, char **<i>last</i>);</b> |
|
93 </P> |
|
94 <P> |
|
95 <b>int pcre_get_substring(const char *<i>subject</i>, int *<i>ovector</i>,</b> |
|
96 <b>int <i>stringcount</i>, int <i>stringnumber</i>,</b> |
|
97 <b>const char **<i>stringptr</i>);</b> |
|
98 </P> |
|
99 <P> |
|
100 <b>int pcre_get_substring_list(const char *<i>subject</i>,</b> |
|
101 <b>int *<i>ovector</i>, int <i>stringcount</i>, const char ***<i>listptr</i>);</b> |
|
102 </P> |
|
103 <P> |
|
104 <b>void pcre_free_substring(const char *<i>stringptr</i>);</b> |
|
105 </P> |
|
106 <P> |
|
107 <b>void pcre_free_substring_list(const char **<i>stringptr</i>);</b> |
|
108 </P> |
|
109 <P> |
|
110 <b>const unsigned char *pcre_maketables(void);</b> |
|
111 </P> |
|
112 <P> |
|
113 <b>int pcre_fullinfo(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> |
|
114 <b>int <i>what</i>, void *<i>where</i>);</b> |
|
115 </P> |
|
116 <P> |
|
117 <b>int pcre_info(const pcre *<i>code</i>, int *<i>optptr</i>, int</b> |
|
118 <b>*<i>firstcharptr</i>);</b> |
|
119 </P> |
|
120 <P> |
|
121 <b>int pcre_refcount(pcre *<i>code</i>, int <i>adjust</i>);</b> |
|
122 </P> |
|
123 <P> |
|
124 <b>int pcre_config(int <i>what</i>, void *<i>where</i>);</b> |
|
125 </P> |
|
126 <P> |
|
127 <b>char *pcre_version(void);</b> |
|
128 </P> |
|
129 <P> |
|
130 <b>void *(*pcre_malloc)(size_t);</b> |
|
131 </P> |
|
132 <P> |
|
133 <b>void (*pcre_free)(void *);</b> |
|
134 </P> |
|
135 <P> |
|
136 <b>void *(*pcre_stack_malloc)(size_t);</b> |
|
137 </P> |
|
138 <P> |
|
139 <b>void (*pcre_stack_free)(void *);</b> |
|
140 </P> |
|
141 <P> |
|
142 <b>int (*pcre_callout)(pcre_callout_block *);</b> |
|
143 </P> |
|
144 <br><a name="SEC2" href="#TOC1">PCRE API OVERVIEW</a><br> |
|
145 <P> |
|
146 PCRE has its own native API, which is described in this document. There are |
|
147 also some wrapper functions that correspond to the POSIX regular expression |
|
148 API. These are described in the |
|
149 <a href="pcreposix.html"><b>pcreposix</b></a> |
|
150 documentation. Both of these APIs define a set of C function calls. A C++ |
|
151 wrapper is distributed with PCRE. It is documented in the |
|
152 <a href="pcrecpp.html"><b>pcrecpp</b></a> |
|
153 page. |
|
154 </P> |
|
155 <P> |
|
156 The native API C function prototypes are defined in the header file |
|
157 <b>pcre.h</b>, and on Unix systems the library itself is called <b>libpcre</b>. |
|
158 It can normally be accessed by adding <b>-lpcre</b> to the command for linking |
|
159 an application that uses PCRE. The header file defines the macros PCRE_MAJOR |
|
160 and PCRE_MINOR to contain the major and minor release numbers for the library. |
|
161 Applications can use these to include support for different releases of PCRE. |
|
162 </P> |
|
163 <P> |
|
164 The functions <b>pcre_compile()</b>, <b>pcre_compile2()</b>, <b>pcre_study()</b>, |
|
165 and <b>pcre_exec()</b> are used for compiling and matching regular expressions |
|
166 in a Perl-compatible manner. A sample program that demonstrates the simplest |
|
167 way of using them is provided in the file called <i>pcredemo.c</i> in the source |
|
168 distribution. The |
|
169 <a href="pcresample.html"><b>pcresample</b></a> |
|
170 documentation describes how to compile and run it. |
|
171 </P> |
|
172 <P> |
|
173 A second matching function, <b>pcre_dfa_exec()</b>, which is not |
|
174 Perl-compatible, is also provided. This uses a different algorithm for the |
|
175 matching. The alternative algorithm finds all possible matches (at a given |
|
176 point in the subject), and scans the subject just once. However, this algorithm |
|
177 does not return captured substrings. A description of the two matching |
|
178 algorithms and their advantages and disadvantages is given in the |
|
179 <a href="pcrematching.html"><b>pcrematching</b></a> |
|
180 documentation. |
|
181 </P> |
|
182 <P> |
|
183 In addition to the main compiling and matching functions, there are convenience |
|
184 functions for extracting captured substrings from a subject string that is |
|
185 matched by <b>pcre_exec()</b>. They are: |
|
186 <pre> |
|
187 <b>pcre_copy_substring()</b> |
|
188 <b>pcre_copy_named_substring()</b> |
|
189 <b>pcre_get_substring()</b> |
|
190 <b>pcre_get_named_substring()</b> |
|
191 <b>pcre_get_substring_list()</b> |
|
192 <b>pcre_get_stringnumber()</b> |
|
193 <b>pcre_get_stringtable_entries()</b> |
|
194 </pre> |
|
195 <b>pcre_free_substring()</b> and <b>pcre_free_substring_list()</b> are also |
|
196 provided, to free the memory used for extracted strings. |
|
197 </P> |
|
198 <P> |
|
199 The function <b>pcre_maketables()</b> is used to build a set of character tables |
|
200 in the current locale for passing to <b>pcre_compile()</b>, <b>pcre_exec()</b>, |
|
201 or <b>pcre_dfa_exec()</b>. This is an optional facility that is provided for |
|
202 specialist use. Most commonly, no special tables are passed, in which case |
|
203 internal tables that are generated when PCRE is built are used. |
|
204 </P> |
|
205 <P> |
|
206 The function <b>pcre_fullinfo()</b> is used to find out information about a |
|
207 compiled pattern; <b>pcre_info()</b> is an obsolete version that returns only |
|
208 some of the available information, but is retained for backwards compatibility. |
|
209 The function <b>pcre_version()</b> returns a pointer to a string containing the |
|
210 version of PCRE and its date of release. |
|
211 </P> |
|
212 <P> |
|
213 The function <b>pcre_refcount()</b> maintains a reference count in a data block |
|
214 containing a compiled pattern. This is provided for the benefit of |
|
215 object-oriented applications. |
|
216 </P> |
|
217 <P> |
|
218 The global variables <b>pcre_malloc</b> and <b>pcre_free</b> initially contain |
|
219 the entry points of the standard <b>malloc()</b> and <b>free()</b> functions, |
|
220 respectively. PCRE calls the memory management functions via these variables, |
|
221 so a calling program can replace them if it wishes to intercept the calls. This |
|
222 should be done before calling any PCRE functions. |
|
223 </P> |
|
224 <P> |
|
225 The global variables <b>pcre_stack_malloc</b> and <b>pcre_stack_free</b> are also |
|
226 indirections to memory management functions. These special functions are used |
|
227 only when PCRE is compiled to use the heap for remembering data, instead of |
|
228 recursive function calls, when running the <b>pcre_exec()</b> function. See the |
|
229 <a href="pcrebuild.html"><b>pcrebuild</b></a> |
|
230 documentation for details of how to do this. It is a non-standard way of |
|
231 building PCRE, for use in environments that have limited stacks. Because of the |
|
232 greater use of memory management, it runs more slowly. Separate functions are |
|
233 provided so that special-purpose external code can be used for this case. When |
|
234 used, these functions are always called in a stack-like manner (last obtained, |
|
235 first freed), and always for memory blocks of the same size. There is a |
|
236 discussion about PCRE's stack usage in the |
|
237 <a href="pcrestack.html"><b>pcrestack</b></a> |
|
238 documentation. |
|
239 </P> |
|
240 <P> |
|
241 The global variable <b>pcre_callout</b> initially contains NULL. It can be set |
|
242 by the caller to a "callout" function, which PCRE will then call at specified |
|
243 points during a matching operation. Details are given in the |
|
244 <a href="pcrecallout.html"><b>pcrecallout</b></a> |
|
245 documentation. |
|
246 <a name="newlines"></a></P> |
|
247 <br><a name="SEC3" href="#TOC1">NEWLINES</a><br> |
|
248 <P> |
|
249 PCRE supports five different conventions for indicating line breaks in |
|
250 strings: a single CR (carriage return) character, a single LF (linefeed) |
|
251 character, the two-character sequence CRLF, any of the three preceding, or any |
|
252 Unicode newline sequence. The Unicode newline sequences are the three just |
|
253 mentioned, plus the single characters VT (vertical tab, U+000B), FF (formfeed, |
|
254 U+000C), NEL (next line, U+0085), LS (line separator, U+2028), and PS |
|
255 (paragraph separator, U+2029). |
|
256 </P> |
|
257 <P> |
|
258 Each of the first three conventions is used by at least one operating system as |
|
259 its standard newline sequence. When PCRE is built, a default can be specified. |
|
260 The default default is LF, which is the Unix standard. When PCRE is run, the |
|
261 default can be overridden, either when a pattern is compiled, or when it is |
|
262 matched. |
|
263 </P> |
|
264 <P> |
|
265 At compile time, the newline convention can be specified by the <i>options</i> |
|
266 argument of <b>pcre_compile()</b>, or it can be specified by special text at the |
|
267 start of the pattern itself; this overrides any other settings. See the |
|
268 <a href="pcrepattern.html"><b>pcrepattern</b></a> |
|
269 page for details of the special character sequences. |
|
270 </P> |
|
271 <P> |
|
272 In the PCRE documentation the word "newline" is used to mean "the character or |
|
273 pair of characters that indicate a line break". The choice of newline |
|
274 convention affects the handling of the dot, circumflex, and dollar |
|
275 metacharacters, the handling of #-comments in /x mode, and, when CRLF is a |
|
276 recognized line ending sequence, the match position advancement for a |
|
277 non-anchored pattern. There is more detail about this in the |
|
278 <a href="#execoptions">section on <b>pcre_exec()</b> options</a> |
|
279 below. |
|
280 </P> |
|
281 <P> |
|
282 The choice of newline convention does not affect the interpretation of |
|
283 the \n or \r escape sequences, nor does it affect what \R matches, which is |
|
284 controlled in a similar way, but by separate options. |
|
285 </P> |
|
286 <br><a name="SEC4" href="#TOC1">MULTITHREADING</a><br> |
|
287 <P> |
|
288 The PCRE functions can be used in multi-threading applications, with the |
|
289 proviso that the memory management functions pointed to by <b>pcre_malloc</b>, |
|
290 <b>pcre_free</b>, <b>pcre_stack_malloc</b>, and <b>pcre_stack_free</b>, and the |
|
291 callout function pointed to by <b>pcre_callout</b>, are shared by all threads. |
|
292 </P> |
|
293 <P> |
|
294 The compiled form of a regular expression is not altered during matching, so |
|
295 the same compiled pattern can safely be used by several threads at once. |
|
296 </P> |
|
297 <br><a name="SEC5" href="#TOC1">SAVING PRECOMPILED PATTERNS FOR LATER USE</a><br> |
|
298 <P> |
|
299 The compiled form of a regular expression can be saved and re-used at a later |
|
300 time, possibly by a different program, and even on a host other than the one on |
|
301 which it was compiled. Details are given in the |
|
302 <a href="pcreprecompile.html"><b>pcreprecompile</b></a> |
|
303 documentation. However, compiling a regular expression with one version of PCRE |
|
304 for use with a different version is not guaranteed to work and may cause |
|
305 crashes. |
|
306 </P> |
|
307 <br><a name="SEC6" href="#TOC1">CHECKING BUILD-TIME OPTIONS</a><br> |
|
308 <P> |
|
309 <b>int pcre_config(int <i>what</i>, void *<i>where</i>);</b> |
|
310 </P> |
|
311 <P> |
|
312 The function <b>pcre_config()</b> makes it possible for a PCRE client to |
|
313 discover which optional features have been compiled into the PCRE library. The |
|
314 <a href="pcrebuild.html"><b>pcrebuild</b></a> |
|
315 documentation has more details about these optional features. |
|
316 </P> |
|
317 <P> |
|
318 The first argument for <b>pcre_config()</b> is an integer, specifying which |
|
319 information is required; the second argument is a pointer to a variable into |
|
320 which the information is placed. The following information is available: |
|
321 <pre> |
|
322 PCRE_CONFIG_UTF8 |
|
323 </pre> |
|
324 The output is an integer that is set to one if UTF-8 support is available; |
|
325 otherwise it is set to zero. |
|
326 <pre> |
|
327 PCRE_CONFIG_UNICODE_PROPERTIES |
|
328 </pre> |
|
329 The output is an integer that is set to one if support for Unicode character |
|
330 properties is available; otherwise it is set to zero. |
|
331 <pre> |
|
332 PCRE_CONFIG_NEWLINE |
|
333 </pre> |
|
334 The output is an integer whose value specifies the default character sequence |
|
335 that is recognized as meaning "newline". The four values that are supported |
|
336 are: 10 for LF, 13 for CR, 3338 for CRLF, -2 for ANYCRLF, and -1 for ANY. The |
|
337 default should normally be the standard sequence for your operating system. |
|
338 <pre> |
|
339 PCRE_CONFIG_BSR |
|
340 </pre> |
|
341 The output is an integer whose value indicates what character sequences the \R |
|
342 escape sequence matches by default. A value of 0 means that \R matches any |
|
343 Unicode line ending sequence; a value of 1 means that \R matches only CR, LF, |
|
344 or CRLF. The default can be overridden when a pattern is compiled or matched. |
|
345 <pre> |
|
346 PCRE_CONFIG_LINK_SIZE |
|
347 </pre> |
|
348 The output is an integer that contains the number of bytes used for internal |
|
349 linkage in compiled regular expressions. The value is 2, 3, or 4. Larger values |
|
350 allow larger regular expressions to be compiled, at the expense of slower |
|
351 matching. The default value of 2 is sufficient for all but the most massive |
|
352 patterns, since it allows the compiled pattern to be up to 64K in size. |
|
353 <pre> |
|
354 PCRE_CONFIG_POSIX_MALLOC_THRESHOLD |
|
355 </pre> |
|
356 The output is an integer that contains the threshold above which the POSIX |
|
357 interface uses <b>malloc()</b> for output vectors. Further details are given in |
|
358 the |
|
359 <a href="pcreposix.html"><b>pcreposix</b></a> |
|
360 documentation. |
|
361 <pre> |
|
362 PCRE_CONFIG_MATCH_LIMIT |
|
363 </pre> |
|
364 The output is an integer that gives the default limit for the number of |
|
365 internal matching function calls in a <b>pcre_exec()</b> execution. Further |
|
366 details are given with <b>pcre_exec()</b> below. |
|
367 <pre> |
|
368 PCRE_CONFIG_MATCH_LIMIT_RECURSION |
|
369 </pre> |
|
370 The output is an integer that gives the default limit for the depth of |
|
371 recursion when calling the internal matching function in a <b>pcre_exec()</b> |
|
372 execution. Further details are given with <b>pcre_exec()</b> below. |
|
373 <pre> |
|
374 PCRE_CONFIG_STACKRECURSE |
|
375 </pre> |
|
376 The output is an integer that is set to one if internal recursion when running |
|
377 <b>pcre_exec()</b> is implemented by recursive function calls that use the stack |
|
378 to remember their state. This is the usual way that PCRE is compiled. The |
|
379 output is zero if PCRE was compiled to use blocks of data on the heap instead |
|
380 of recursive function calls. In this case, <b>pcre_stack_malloc</b> and |
|
381 <b>pcre_stack_free</b> are called to manage memory blocks on the heap, thus |
|
382 avoiding the use of the stack. |
|
383 </P> |
|
384 <br><a name="SEC7" href="#TOC1">COMPILING A PATTERN</a><br> |
|
385 <P> |
|
386 <b>pcre *pcre_compile(const char *<i>pattern</i>, int <i>options</i>,</b> |
|
387 <b>const char **<i>errptr</i>, int *<i>erroffset</i>,</b> |
|
388 <b>const unsigned char *<i>tableptr</i>);</b> |
|
389 <b>pcre *pcre_compile2(const char *<i>pattern</i>, int <i>options</i>,</b> |
|
390 <b>int *<i>errorcodeptr</i>,</b> |
|
391 <b>const char **<i>errptr</i>, int *<i>erroffset</i>,</b> |
|
392 <b>const unsigned char *<i>tableptr</i>);</b> |
|
393 </P> |
|
394 <P> |
|
395 Either of the functions <b>pcre_compile()</b> or <b>pcre_compile2()</b> can be |
|
396 called to compile a pattern into an internal form. The only difference between |
|
397 the two interfaces is that <b>pcre_compile2()</b> has an additional argument, |
|
398 <i>errorcodeptr</i>, via which a numerical error code can be returned. |
|
399 </P> |
|
400 <P> |
|
401 The pattern is a C string terminated by a binary zero, and is passed in the |
|
402 <i>pattern</i> argument. A pointer to a single block of memory that is obtained |
|
403 via <b>pcre_malloc</b> is returned. This contains the compiled code and related |
|
404 data. The <b>pcre</b> type is defined for the returned block; this is a typedef |
|
405 for a structure whose contents are not externally defined. It is up to the |
|
406 caller to free the memory (via <b>pcre_free</b>) when it is no longer required. |
|
407 </P> |
|
408 <P> |
|
409 Although the compiled code of a PCRE regex is relocatable, that is, it does not |
|
410 depend on memory location, the complete <b>pcre</b> data block is not |
|
411 fully relocatable, because it may contain a copy of the <i>tableptr</i> |
|
412 argument, which is an address (see below). |
|
413 </P> |
|
414 <P> |
|
415 The <i>options</i> argument contains various bit settings that affect the |
|
416 compilation. It should be zero if no options are required. The available |
|
417 options are described below. Some of them, in particular, those that are |
|
418 compatible with Perl, can also be set and unset from within the pattern (see |
|
419 the detailed description in the |
|
420 <a href="pcrepattern.html"><b>pcrepattern</b></a> |
|
421 documentation). For these options, the contents of the <i>options</i> argument |
|
422 specifies their initial settings at the start of compilation and execution. The |
|
423 PCRE_ANCHORED and PCRE_NEWLINE_<i>xxx</i> options can be set at the time of |
|
424 matching as well as at compile time. |
|
425 </P> |
|
426 <P> |
|
427 If <i>errptr</i> is NULL, <b>pcre_compile()</b> returns NULL immediately. |
|
428 Otherwise, if compilation of a pattern fails, <b>pcre_compile()</b> returns |
|
429 NULL, and sets the variable pointed to by <i>errptr</i> to point to a textual |
|
430 error message. This is a static string that is part of the library. You must |
|
431 not try to free it. The offset from the start of the pattern to the character |
|
432 where the error was discovered is placed in the variable pointed to by |
|
433 <i>erroffset</i>, which must not be NULL. If it is, an immediate error is given. |
|
434 </P> |
|
435 <P> |
|
436 If <b>pcre_compile2()</b> is used instead of <b>pcre_compile()</b>, and the |
|
437 <i>errorcodeptr</i> argument is not NULL, a non-zero error code number is |
|
438 returned via this argument in the event of an error. This is in addition to the |
|
439 textual error message. Error codes and messages are listed below. |
|
440 </P> |
|
441 <P> |
|
442 If the final argument, <i>tableptr</i>, is NULL, PCRE uses a default set of |
|
443 character tables that are built when PCRE is compiled, using the default C |
|
444 locale. Otherwise, <i>tableptr</i> must be an address that is the result of a |
|
445 call to <b>pcre_maketables()</b>. This value is stored with the compiled |
|
446 pattern, and used again by <b>pcre_exec()</b>, unless another table pointer is |
|
447 passed to it. For more discussion, see the section on locale support below. |
|
448 </P> |
|
449 <P> |
|
450 This code fragment shows a typical straightforward call to <b>pcre_compile()</b>: |
|
451 <pre> |
|
452 pcre *re; |
|
453 const char *error; |
|
454 int erroffset; |
|
455 re = pcre_compile( |
|
456 "^A.*Z", /* the pattern */ |
|
457 0, /* default options */ |
|
458 &error, /* for error message */ |
|
459 &erroffset, /* for error offset */ |
|
460 NULL); /* use default character tables */ |
|
461 </pre> |
|
462 The following names for option bits are defined in the <b>pcre.h</b> header |
|
463 file: |
|
464 <pre> |
|
465 PCRE_ANCHORED |
|
466 </pre> |
|
467 If this bit is set, the pattern is forced to be "anchored", that is, it is |
|
468 constrained to match only at the first matching point in the string that is |
|
469 being searched (the "subject string"). This effect can also be achieved by |
|
470 appropriate constructs in the pattern itself, which is the only way to do it in |
|
471 Perl. |
|
472 <pre> |
|
473 PCRE_AUTO_CALLOUT |
|
474 </pre> |
|
475 If this bit is set, <b>pcre_compile()</b> automatically inserts callout items, |
|
476 all with number 255, before each pattern item. For discussion of the callout |
|
477 facility, see the |
|
478 <a href="pcrecallout.html"><b>pcrecallout</b></a> |
|
479 documentation. |
|
480 <pre> |
|
481 PCRE_BSR_ANYCRLF |
|
482 PCRE_BSR_UNICODE |
|
483 </pre> |
|
484 These options (which are mutually exclusive) control what the \R escape |
|
485 sequence matches. The choice is either to match only CR, LF, or CRLF, or to |
|
486 match any Unicode newline sequence. The default is specified when PCRE is |
|
487 built. It can be overridden from within the pattern, or by setting an option |
|
488 when a compiled pattern is matched. |
|
489 <pre> |
|
490 PCRE_CASELESS |
|
491 </pre> |
|
492 If this bit is set, letters in the pattern match both upper and lower case |
|
493 letters. It is equivalent to Perl's /i option, and it can be changed within a |
|
494 pattern by a (?i) option setting. In UTF-8 mode, PCRE always understands the |
|
495 concept of case for characters whose values are less than 128, so caseless |
|
496 matching is always possible. For characters with higher values, the concept of |
|
497 case is supported if PCRE is compiled with Unicode property support, but not |
|
498 otherwise. If you want to use caseless matching for characters 128 and above, |
|
499 you must ensure that PCRE is compiled with Unicode property support as well as |
|
500 with UTF-8 support. |
|
501 <pre> |
|
502 PCRE_DOLLAR_ENDONLY |
|
503 </pre> |
|
504 If this bit is set, a dollar metacharacter in the pattern matches only at the |
|
505 end of the subject string. Without this option, a dollar also matches |
|
506 immediately before a newline at the end of the string (but not before any other |
|
507 newlines). The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is set. |
|
508 There is no equivalent to this option in Perl, and no way to set it within a |
|
509 pattern. |
|
510 <pre> |
|
511 PCRE_DOTALL |
|
512 </pre> |
|
513 If this bit is set, a dot metacharater in the pattern matches all characters, |
|
514 including those that indicate newline. Without it, a dot does not match when |
|
515 the current position is at a newline. This option is equivalent to Perl's /s |
|
516 option, and it can be changed within a pattern by a (?s) option setting. A |
|
517 negative class such as [^a] always matches newline characters, independent of |
|
518 the setting of this option. |
|
519 <pre> |
|
520 PCRE_DUPNAMES |
|
521 </pre> |
|
522 If this bit is set, names used to identify capturing subpatterns need not be |
|
523 unique. This can be helpful for certain types of pattern when it is known that |
|
524 only one instance of the named subpattern can ever be matched. There are more |
|
525 details of named subpatterns below; see also the |
|
526 <a href="pcrepattern.html"><b>pcrepattern</b></a> |
|
527 documentation. |
|
528 <pre> |
|
529 PCRE_EXTENDED |
|
530 </pre> |
|
531 If this bit is set, whitespace data characters in the pattern are totally |
|
532 ignored except when escaped or inside a character class. Whitespace does not |
|
533 include the VT character (code 11). In addition, characters between an |
|
534 unescaped # outside a character class and the next newline, inclusive, are also |
|
535 ignored. This is equivalent to Perl's /x option, and it can be changed within a |
|
536 pattern by a (?x) option setting. |
|
537 </P> |
|
538 <P> |
|
539 This option makes it possible to include comments inside complicated patterns. |
|
540 Note, however, that this applies only to data characters. Whitespace characters |
|
541 may never appear within special character sequences in a pattern, for example |
|
542 within the sequence (?( which introduces a conditional subpattern. |
|
543 <pre> |
|
544 PCRE_EXTRA |
|
545 </pre> |
|
546 This option was invented in order to turn on additional functionality of PCRE |
|
547 that is incompatible with Perl, but it is currently of very little use. When |
|
548 set, any backslash in a pattern that is followed by a letter that has no |
|
549 special meaning causes an error, thus reserving these combinations for future |
|
550 expansion. By default, as in Perl, a backslash followed by a letter with no |
|
551 special meaning is treated as a literal. (Perl can, however, be persuaded to |
|
552 give a warning for this.) There are at present no other features controlled by |
|
553 this option. It can also be set by a (?X) option setting within a pattern. |
|
554 <pre> |
|
555 PCRE_FIRSTLINE |
|
556 </pre> |
|
557 If this option is set, an unanchored pattern is required to match before or at |
|
558 the first newline in the subject string, though the matched text may continue |
|
559 over the newline. |
|
560 <pre> |
|
561 PCRE_JAVASCRIPT_COMPAT |
|
562 </pre> |
|
563 If this option is set, PCRE's behaviour is changed in some ways so that it is |
|
564 compatible with JavaScript rather than Perl. The changes are as follows: |
|
565 </P> |
|
566 <P> |
|
567 (1) A lone closing square bracket in a pattern causes a compile-time error, |
|
568 because this is illegal in JavaScript (by default it is treated as a data |
|
569 character). Thus, the pattern AB]CD becomes illegal when this option is set. |
|
570 </P> |
|
571 <P> |
|
572 (2) At run time, a back reference to an unset subpattern group matches an empty |
|
573 string (by default this causes the current matching alternative to fail). A |
|
574 pattern such as (\1)(a) succeeds when this option is set (assuming it can find |
|
575 an "a" in the subject), whereas it fails by default, for Perl compatibility. |
|
576 <pre> |
|
577 PCRE_MULTILINE |
|
578 </pre> |
|
579 By default, PCRE treats the subject string as consisting of a single line of |
|
580 characters (even if it actually contains newlines). The "start of line" |
|
581 metacharacter (^) matches only at the start of the string, while the "end of |
|
582 line" metacharacter ($) matches only at the end of the string, or before a |
|
583 terminating newline (unless PCRE_DOLLAR_ENDONLY is set). This is the same as |
|
584 Perl. |
|
585 </P> |
|
586 <P> |
|
587 When PCRE_MULTILINE it is set, the "start of line" and "end of line" constructs |
|
588 match immediately following or immediately before internal newlines in the |
|
589 subject string, respectively, as well as at the very start and end. This is |
|
590 equivalent to Perl's /m option, and it can be changed within a pattern by a |
|
591 (?m) option setting. If there are no newlines in a subject string, or no |
|
592 occurrences of ^ or $ in a pattern, setting PCRE_MULTILINE has no effect. |
|
593 <pre> |
|
594 PCRE_NEWLINE_CR |
|
595 PCRE_NEWLINE_LF |
|
596 PCRE_NEWLINE_CRLF |
|
597 PCRE_NEWLINE_ANYCRLF |
|
598 PCRE_NEWLINE_ANY |
|
599 </pre> |
|
600 These options override the default newline definition that was chosen when PCRE |
|
601 was built. Setting the first or the second specifies that a newline is |
|
602 indicated by a single character (CR or LF, respectively). Setting |
|
603 PCRE_NEWLINE_CRLF specifies that a newline is indicated by the two-character |
|
604 CRLF sequence. Setting PCRE_NEWLINE_ANYCRLF specifies that any of the three |
|
605 preceding sequences should be recognized. Setting PCRE_NEWLINE_ANY specifies |
|
606 that any Unicode newline sequence should be recognized. The Unicode newline |
|
607 sequences are the three just mentioned, plus the single characters VT (vertical |
|
608 tab, U+000B), FF (formfeed, U+000C), NEL (next line, U+0085), LS (line |
|
609 separator, U+2028), and PS (paragraph separator, U+2029). The last two are |
|
610 recognized only in UTF-8 mode. |
|
611 </P> |
|
612 <P> |
|
613 The newline setting in the options word uses three bits that are treated |
|
614 as a number, giving eight possibilities. Currently only six are used (default |
|
615 plus the five values above). This means that if you set more than one newline |
|
616 option, the combination may or may not be sensible. For example, |
|
617 PCRE_NEWLINE_CR with PCRE_NEWLINE_LF is equivalent to PCRE_NEWLINE_CRLF, but |
|
618 other combinations may yield unused numbers and cause an error. |
|
619 </P> |
|
620 <P> |
|
621 The only time that a line break is specially recognized when compiling a |
|
622 pattern is if PCRE_EXTENDED is set, and an unescaped # outside a character |
|
623 class is encountered. This indicates a comment that lasts until after the next |
|
624 line break sequence. In other circumstances, line break sequences are treated |
|
625 as literal data, except that in PCRE_EXTENDED mode, both CR and LF are treated |
|
626 as whitespace characters and are therefore ignored. |
|
627 </P> |
|
628 <P> |
|
629 The newline option that is set at compile time becomes the default that is used |
|
630 for <b>pcre_exec()</b> and <b>pcre_dfa_exec()</b>, but it can be overridden. |
|
631 <pre> |
|
632 PCRE_NO_AUTO_CAPTURE |
|
633 </pre> |
|
634 If this option is set, it disables the use of numbered capturing parentheses in |
|
635 the pattern. Any opening parenthesis that is not followed by ? behaves as if it |
|
636 were followed by ?: but named parentheses can still be used for capturing (and |
|
637 they acquire numbers in the usual way). There is no equivalent of this option |
|
638 in Perl. |
|
639 <pre> |
|
640 PCRE_UNGREEDY |
|
641 </pre> |
|
642 This option inverts the "greediness" of the quantifiers so that they are not |
|
643 greedy by default, but become greedy if followed by "?". It is not compatible |
|
644 with Perl. It can also be set by a (?U) option setting within the pattern. |
|
645 <pre> |
|
646 PCRE_UTF8 |
|
647 </pre> |
|
648 This option causes PCRE to regard both the pattern and the subject as strings |
|
649 of UTF-8 characters instead of single-byte character strings. However, it is |
|
650 available only when PCRE is built to include UTF-8 support. If not, the use |
|
651 of this option provokes an error. Details of how this option changes the |
|
652 behaviour of PCRE are given in the |
|
653 <a href="pcre.html#utf8support">section on UTF-8 support</a> |
|
654 in the main |
|
655 <a href="pcre.html"><b>pcre</b></a> |
|
656 page. |
|
657 <pre> |
|
658 PCRE_NO_UTF8_CHECK |
|
659 </pre> |
|
660 When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string is |
|
661 automatically checked. There is a discussion about the |
|
662 <a href="pcre.html#utf8strings">validity of UTF-8 strings</a> |
|
663 in the main |
|
664 <a href="pcre.html"><b>pcre</b></a> |
|
665 page. If an invalid UTF-8 sequence of bytes is found, <b>pcre_compile()</b> |
|
666 returns an error. If you already know that your pattern is valid, and you want |
|
667 to skip this check for performance reasons, you can set the PCRE_NO_UTF8_CHECK |
|
668 option. When it is set, the effect of passing an invalid UTF-8 string as a |
|
669 pattern is undefined. It may cause your program to crash. Note that this option |
|
670 can also be passed to <b>pcre_exec()</b> and <b>pcre_dfa_exec()</b>, to suppress |
|
671 the UTF-8 validity checking of subject strings. |
|
672 </P> |
|
673 <br><a name="SEC8" href="#TOC1">COMPILATION ERROR CODES</a><br> |
|
674 <P> |
|
675 The following table lists the error codes than may be returned by |
|
676 <b>pcre_compile2()</b>, along with the error messages that may be returned by |
|
677 both compiling functions. As PCRE has developed, some error codes have fallen |
|
678 out of use. To avoid confusion, they have not been re-used. |
|
679 <pre> |
|
680 0 no error |
|
681 1 \ at end of pattern |
|
682 2 \c at end of pattern |
|
683 3 unrecognized character follows \ |
|
684 4 numbers out of order in {} quantifier |
|
685 5 number too big in {} quantifier |
|
686 6 missing terminating ] for character class |
|
687 7 invalid escape sequence in character class |
|
688 8 range out of order in character class |
|
689 9 nothing to repeat |
|
690 10 [this code is not in use] |
|
691 11 internal error: unexpected repeat |
|
692 12 unrecognized character after (? or (?- |
|
693 13 POSIX named classes are supported only within a class |
|
694 14 missing ) |
|
695 15 reference to non-existent subpattern |
|
696 16 erroffset passed as NULL |
|
697 17 unknown option bit(s) set |
|
698 18 missing ) after comment |
|
699 19 [this code is not in use] |
|
700 20 regular expression is too large |
|
701 21 failed to get memory |
|
702 22 unmatched parentheses |
|
703 23 internal error: code overflow |
|
704 24 unrecognized character after (?< |
|
705 25 lookbehind assertion is not fixed length |
|
706 26 malformed number or name after (?( |
|
707 27 conditional group contains more than two branches |
|
708 28 assertion expected after (?( |
|
709 29 (?R or (?[+-]digits must be followed by ) |
|
710 30 unknown POSIX class name |
|
711 31 POSIX collating elements are not supported |
|
712 32 this version of PCRE is not compiled with PCRE_UTF8 support |
|
713 33 [this code is not in use] |
|
714 34 character value in \x{...} sequence is too large |
|
715 35 invalid condition (?(0) |
|
716 36 \C not allowed in lookbehind assertion |
|
717 37 PCRE does not support \L, \l, \N, \U, or \u |
|
718 38 number after (?C is > 255 |
|
719 39 closing ) for (?C expected |
|
720 40 recursive call could loop indefinitely |
|
721 41 unrecognized character after (?P |
|
722 42 syntax error in subpattern name (missing terminator) |
|
723 43 two named subpatterns have the same name |
|
724 44 invalid UTF-8 string |
|
725 45 support for \P, \p, and \X has not been compiled |
|
726 46 malformed \P or \p sequence |
|
727 47 unknown property name after \P or \p |
|
728 48 subpattern name is too long (maximum 32 characters) |
|
729 49 too many named subpatterns (maximum 10000) |
|
730 50 [this code is not in use] |
|
731 51 octal value is greater than \377 (not in UTF-8 mode) |
|
732 52 internal error: overran compiling workspace |
|
733 53 internal error: previously-checked referenced subpattern not found |
|
734 54 DEFINE group contains more than one branch |
|
735 55 repeating a DEFINE group is not allowed |
|
736 56 inconsistent NEWLINE options |
|
737 57 \g is not followed by a braced, angle-bracketed, or quoted |
|
738 name/number or by a plain number |
|
739 58 a numbered reference must not be zero |
|
740 59 (*VERB) with an argument is not supported |
|
741 60 (*VERB) not recognized |
|
742 61 number is too big |
|
743 62 subpattern name expected |
|
744 63 digit expected after (?+ |
|
745 64 ] is an invalid data character in JavaScript compatibility mode |
|
746 </pre> |
|
747 The numbers 32 and 10000 in errors 48 and 49 are defaults; different values may |
|
748 be used if the limits were changed when PCRE was built. |
|
749 </P> |
|
750 <br><a name="SEC9" href="#TOC1">STUDYING A PATTERN</a><br> |
|
751 <P> |
|
752 <b>pcre_extra *pcre_study(const pcre *<i>code</i>, int <i>options</i></b> |
|
753 <b>const char **<i>errptr</i>);</b> |
|
754 </P> |
|
755 <P> |
|
756 If a compiled pattern is going to be used several times, it is worth spending |
|
757 more time analyzing it in order to speed up the time taken for matching. The |
|
758 function <b>pcre_study()</b> takes a pointer to a compiled pattern as its first |
|
759 argument. If studying the pattern produces additional information that will |
|
760 help speed up matching, <b>pcre_study()</b> returns a pointer to a |
|
761 <b>pcre_extra</b> block, in which the <i>study_data</i> field points to the |
|
762 results of the study. |
|
763 </P> |
|
764 <P> |
|
765 The returned value from <b>pcre_study()</b> can be passed directly to |
|
766 <b>pcre_exec()</b>. However, a <b>pcre_extra</b> block also contains other |
|
767 fields that can be set by the caller before the block is passed; these are |
|
768 described |
|
769 <a href="#extradata">below</a> |
|
770 in the section on matching a pattern. |
|
771 </P> |
|
772 <P> |
|
773 If studying the pattern does not produce any additional information |
|
774 <b>pcre_study()</b> returns NULL. In that circumstance, if the calling program |
|
775 wants to pass any of the other fields to <b>pcre_exec()</b>, it must set up its |
|
776 own <b>pcre_extra</b> block. |
|
777 </P> |
|
778 <P> |
|
779 The second argument of <b>pcre_study()</b> contains option bits. At present, no |
|
780 options are defined, and this argument should always be zero. |
|
781 </P> |
|
782 <P> |
|
783 The third argument for <b>pcre_study()</b> is a pointer for an error message. If |
|
784 studying succeeds (even if no data is returned), the variable it points to is |
|
785 set to NULL. Otherwise it is set to point to a textual error message. This is a |
|
786 static string that is part of the library. You must not try to free it. You |
|
787 should test the error pointer for NULL after calling <b>pcre_study()</b>, to be |
|
788 sure that it has run successfully. |
|
789 </P> |
|
790 <P> |
|
791 This is a typical call to <b>pcre_study</b>(): |
|
792 <pre> |
|
793 pcre_extra *pe; |
|
794 pe = pcre_study( |
|
795 re, /* result of pcre_compile() */ |
|
796 0, /* no options exist */ |
|
797 &error); /* set to NULL or points to a message */ |
|
798 </pre> |
|
799 At present, studying a pattern is useful only for non-anchored patterns that do |
|
800 not have a single fixed starting character. A bitmap of possible starting |
|
801 bytes is created. |
|
802 <a name="localesupport"></a></P> |
|
803 <br><a name="SEC10" href="#TOC1">LOCALE SUPPORT</a><br> |
|
804 <P> |
|
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 \w or \d, but |
|
809 can be tested with \p 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 <P> |
|
815 PCRE contains an internal set of tables that are used when the final argument |
|
816 of <b>pcre_compile()</b> is NULL. These are sufficient for many applications. |
|
817 Normally, the internal tables recognize only ASCII characters. However, when |
|
818 PCRE is built, it is possible to cause the internal tables to be rebuilt in the |
|
819 default "C" locale of the local system, which may cause them to be different. |
|
820 </P> |
|
821 <P> |
|
822 The internal tables can always be overridden by tables supplied by the |
|
823 application that calls PCRE. These may be created in a different locale from |
|
824 the default. As more and more applications change to using Unicode, the need |
|
825 for this locale support is expected to die away. |
|
826 </P> |
|
827 <P> |
|
828 External tables are built by calling the <b>pcre_maketables()</b> function, |
|
829 which has no arguments, in the relevant locale. The result can then be passed |
|
830 to <b>pcre_compile()</b> or <b>pcre_exec()</b> as often as necessary. For |
|
831 example, to build and use tables that are appropriate for the French locale |
|
832 (where accented characters with values greater than 128 are treated as letters), |
|
833 the following code could be used: |
|
834 <pre> |
|
835 setlocale(LC_CTYPE, "fr_FR"); |
|
836 tables = pcre_maketables(); |
|
837 re = pcre_compile(..., tables); |
|
838 </pre> |
|
839 The locale name "fr_FR" is used on Linux and other Unix-like systems; if you |
|
840 are using Windows, the name for the French locale is "french". |
|
841 </P> |
|
842 <P> |
|
843 When <b>pcre_maketables()</b> runs, the tables are built in memory that is |
|
844 obtained via <b>pcre_malloc</b>. It is the caller's responsibility to ensure |
|
845 that the memory containing the tables remains available for as long as it is |
|
846 needed. |
|
847 </P> |
|
848 <P> |
|
849 The pointer that is passed to <b>pcre_compile()</b> is saved with the compiled |
|
850 pattern, and the same tables are used via this pointer by <b>pcre_study()</b> |
|
851 and normally also by <b>pcre_exec()</b>. Thus, by default, for any single |
|
852 pattern, compilation, studying and matching all happen in the same locale, but |
|
853 different patterns can be compiled in different locales. |
|
854 </P> |
|
855 <P> |
|
856 It is possible to pass a table pointer or NULL (indicating the use of the |
|
857 internal tables) to <b>pcre_exec()</b>. Although not intended for this purpose, |
|
858 this facility could be used to match a pattern in a different locale from the |
|
859 one in which it was compiled. Passing table pointers at run time is discussed |
|
860 below in the section on matching a pattern. |
|
861 </P> |
|
862 <br><a name="SEC11" href="#TOC1">INFORMATION ABOUT A PATTERN</a><br> |
|
863 <P> |
|
864 <b>int pcre_fullinfo(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> |
|
865 <b>int <i>what</i>, void *<i>where</i>);</b> |
|
866 </P> |
|
867 <P> |
|
868 The <b>pcre_fullinfo()</b> function returns information about a compiled |
|
869 pattern. It replaces the obsolete <b>pcre_info()</b> function, which is |
|
870 nevertheless retained for backwards compability (and is documented below). |
|
871 </P> |
|
872 <P> |
|
873 The first argument for <b>pcre_fullinfo()</b> is a pointer to the compiled |
|
874 pattern. The second argument is the result of <b>pcre_study()</b>, or NULL if |
|
875 the pattern was not studied. The third argument specifies which piece of |
|
876 information is required, and the fourth argument is a pointer to a variable |
|
877 to receive the data. The yield of the function is zero for success, or one of |
|
878 the following negative numbers: |
|
879 <pre> |
|
880 PCRE_ERROR_NULL the argument <i>code</i> was NULL |
|
881 the argument <i>where</i> was NULL |
|
882 PCRE_ERROR_BADMAGIC the "magic number" was not found |
|
883 PCRE_ERROR_BADOPTION the value of <i>what</i> was invalid |
|
884 </pre> |
|
885 The "magic number" is placed at the start of each compiled pattern as an simple |
|
886 check against passing an arbitrary memory pointer. Here is a typical call of |
|
887 <b>pcre_fullinfo()</b>, to obtain the length of the compiled pattern: |
|
888 <pre> |
|
889 int rc; |
|
890 size_t length; |
|
891 rc = pcre_fullinfo( |
|
892 re, /* result of pcre_compile() */ |
|
893 pe, /* result of pcre_study(), or NULL */ |
|
894 PCRE_INFO_SIZE, /* what is required */ |
|
895 &length); /* where to put the data */ |
|
896 </pre> |
|
897 The possible values for the third argument are defined in <b>pcre.h</b>, and are |
|
898 as follows: |
|
899 <pre> |
|
900 PCRE_INFO_BACKREFMAX |
|
901 </pre> |
|
902 Return the number of the highest back reference in the pattern. The fourth |
|
903 argument should point to an <b>int</b> variable. Zero is returned if there are |
|
904 no back references. |
|
905 <pre> |
|
906 PCRE_INFO_CAPTURECOUNT |
|
907 </pre> |
|
908 Return the number of capturing subpatterns in the pattern. The fourth argument |
|
909 should point to an <b>int</b> variable. |
|
910 <pre> |
|
911 PCRE_INFO_DEFAULT_TABLES |
|
912 </pre> |
|
913 Return a pointer to the internal default character tables within PCRE. The |
|
914 fourth argument should point to an <b>unsigned char *</b> variable. This |
|
915 information call is provided for internal use by the <b>pcre_study()</b> |
|
916 function. External callers can cause PCRE to use its internal tables by passing |
|
917 a NULL table pointer. |
|
918 <pre> |
|
919 PCRE_INFO_FIRSTBYTE |
|
920 </pre> |
|
921 Return information about the first byte of any matched string, for a |
|
922 non-anchored pattern. The fourth argument should point to an <b>int</b> |
|
923 variable. (This option used to be called PCRE_INFO_FIRSTCHAR; the old name is |
|
924 still recognized for backwards compatibility.) |
|
925 </P> |
|
926 <P> |
|
927 If there is a fixed first byte, for example, from a pattern such as |
|
928 (cat|cow|coyote), its value is returned. Otherwise, if either |
|
929 <br> |
|
930 <br> |
|
931 (a) the pattern was compiled with the PCRE_MULTILINE option, and every branch |
|
932 starts with "^", or |
|
933 <br> |
|
934 <br> |
|
935 (b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not set |
|
936 (if it were set, the pattern would be anchored), |
|
937 <br> |
|
938 <br> |
|
939 -1 is returned, indicating that the pattern matches only at the start of a |
|
940 subject string or after any newline within the string. Otherwise -2 is |
|
941 returned. For anchored patterns, -2 is returned. |
|
942 <pre> |
|
943 PCRE_INFO_FIRSTTABLE |
|
944 </pre> |
|
945 If the pattern was studied, and this resulted in the construction of a 256-bit |
|
946 table indicating a fixed set of bytes for the first byte in any matching |
|
947 string, a pointer to the table is returned. Otherwise NULL is returned. The |
|
948 fourth argument should point to an <b>unsigned char *</b> variable. |
|
949 <pre> |
|
950 PCRE_INFO_HASCRORLF |
|
951 </pre> |
|
952 Return 1 if the pattern contains any explicit matches for CR or LF characters, |
|
953 otherwise 0. The fourth argument should point to an <b>int</b> variable. An |
|
954 explicit match is either a literal CR or LF character, or \r or \n. |
|
955 <pre> |
|
956 PCRE_INFO_JCHANGED |
|
957 </pre> |
|
958 Return 1 if the (?J) or (?-J) option setting is used in the pattern, otherwise |
|
959 0. The fourth argument should point to an <b>int</b> variable. (?J) and |
|
960 (?-J) set and unset the local PCRE_DUPNAMES option, respectively. |
|
961 <pre> |
|
962 PCRE_INFO_LASTLITERAL |
|
963 </pre> |
|
964 Return the value of the rightmost literal byte that must exist in any matched |
|
965 string, other than at its start, if such a byte has been recorded. The fourth |
|
966 argument should point to an <b>int</b> variable. If there is no such byte, -1 is |
|
967 returned. For anchored patterns, a last literal byte is recorded only if it |
|
968 follows something of variable length. For example, for the pattern |
|
969 /^a\d+z\d+/ the returned value is "z", but for /^a\dz\d/ the returned value |
|
970 is -1. |
|
971 <pre> |
|
972 PCRE_INFO_NAMECOUNT |
|
973 PCRE_INFO_NAMEENTRYSIZE |
|
974 PCRE_INFO_NAMETABLE |
|
975 </pre> |
|
976 PCRE supports the use of named as well as numbered capturing parentheses. The |
|
977 names are just an additional way of identifying the parentheses, which still |
|
978 acquire numbers. Several convenience functions such as |
|
979 <b>pcre_get_named_substring()</b> are provided for extracting captured |
|
980 substrings by name. It is also possible to extract the data directly, by first |
|
981 converting the name to a number in order to access the correct pointers in the |
|
982 output vector (described with <b>pcre_exec()</b> below). To do the conversion, |
|
983 you need to use the name-to-number map, which is described by these three |
|
984 values. |
|
985 </P> |
|
986 <P> |
|
987 The map consists of a number of fixed-size entries. PCRE_INFO_NAMECOUNT gives |
|
988 the number of entries, and PCRE_INFO_NAMEENTRYSIZE gives the size of each |
|
989 entry; both of these return an <b>int</b> value. The entry size depends on the |
|
990 length of the longest name. PCRE_INFO_NAMETABLE returns a pointer to the first |
|
991 entry of the table (a pointer to <b>char</b>). The first two bytes of each entry |
|
992 are the number of the capturing parenthesis, most significant byte first. The |
|
993 rest of the entry is the corresponding name, zero terminated. The names are in |
|
994 alphabetical order. When PCRE_DUPNAMES is set, duplicate names are in order of |
|
995 their parentheses numbers. For example, consider the following pattern (assume |
|
996 PCRE_EXTENDED is set, so white space - including newlines - is ignored): |
|
997 <pre> |
|
998 (?<date> (?<year>(\d\d)?\d\d) - (?<month>\d\d) - (?<day>\d\d) ) |
|
999 </pre> |
|
1000 There are four named subpatterns, so the table has four entries, and each entry |
|
1001 in the table is eight bytes long. The table is as follows, with non-printing |
|
1002 bytes shows in hexadecimal, and undefined bytes shown as ??: |
|
1003 <pre> |
|
1004 00 01 d a t e 00 ?? |
|
1005 00 05 d a y 00 ?? ?? |
|
1006 00 04 m o n t h 00 |
|
1007 00 02 y e a r 00 ?? |
|
1008 </pre> |
|
1009 When writing code to extract data from named subpatterns using the |
|
1010 name-to-number map, remember that the length of the entries is likely to be |
|
1011 different for each compiled pattern. |
|
1012 <pre> |
|
1013 PCRE_INFO_OKPARTIAL |
|
1014 </pre> |
|
1015 Return 1 if the pattern can be used for partial matching, otherwise 0. The |
|
1016 fourth argument should point to an <b>int</b> variable. The |
|
1017 <a href="pcrepartial.html"><b>pcrepartial</b></a> |
|
1018 documentation lists the restrictions that apply to patterns when partial |
|
1019 matching is used. |
|
1020 <pre> |
|
1021 PCRE_INFO_OPTIONS |
|
1022 </pre> |
|
1023 Return a copy of the options with which the pattern was compiled. The fourth |
|
1024 argument should point to an <b>unsigned long int</b> variable. These option bits |
|
1025 are those specified in the call to <b>pcre_compile()</b>, modified by any |
|
1026 top-level option settings at the start of the pattern itself. In other words, |
|
1027 they are the options that will be in force when matching starts. For example, |
|
1028 if the pattern /(?im)abc(?-i)d/ is compiled with the PCRE_EXTENDED option, the |
|
1029 result is PCRE_CASELESS, PCRE_MULTILINE, and PCRE_EXTENDED. |
|
1030 </P> |
|
1031 <P> |
|
1032 A pattern is automatically anchored by PCRE if all of its top-level |
|
1033 alternatives begin with one of the following: |
|
1034 <pre> |
|
1035 ^ unless PCRE_MULTILINE is set |
|
1036 \A always |
|
1037 \G always |
|
1038 .* if PCRE_DOTALL is set and there are no back references to the subpattern in which .* appears |
|
1039 </pre> |
|
1040 For such patterns, the PCRE_ANCHORED bit is set in the options returned by |
|
1041 <b>pcre_fullinfo()</b>. |
|
1042 <pre> |
|
1043 PCRE_INFO_SIZE |
|
1044 </pre> |
|
1045 Return the size of the compiled pattern, that is, the value that was passed as |
|
1046 the argument to <b>pcre_malloc()</b> when PCRE was getting memory in which to |
|
1047 place the compiled data. The fourth argument should point to a <b>size_t</b> |
|
1048 variable. |
|
1049 <pre> |
|
1050 PCRE_INFO_STUDYSIZE |
|
1051 </pre> |
|
1052 Return the size of the data block pointed to by the <i>study_data</i> field in |
|
1053 a <b>pcre_extra</b> block. That is, it is the value that was passed to |
|
1054 <b>pcre_malloc()</b> when PCRE was getting memory into which to place the data |
|
1055 created by <b>pcre_study()</b>. The fourth argument should point to a |
|
1056 <b>size_t</b> variable. |
|
1057 </P> |
|
1058 <br><a name="SEC12" href="#TOC1">OBSOLETE INFO FUNCTION</a><br> |
|
1059 <P> |
|
1060 <b>int pcre_info(const pcre *<i>code</i>, int *<i>optptr</i>, int</b> |
|
1061 <b>*<i>firstcharptr</i>);</b> |
|
1062 </P> |
|
1063 <P> |
|
1064 The <b>pcre_info()</b> function is now obsolete because its interface is too |
|
1065 restrictive to return all the available data about a compiled pattern. New |
|
1066 programs should use <b>pcre_fullinfo()</b> instead. The yield of |
|
1067 <b>pcre_info()</b> is the number of capturing subpatterns, or one of the |
|
1068 following negative numbers: |
|
1069 <pre> |
|
1070 PCRE_ERROR_NULL the argument <i>code</i> was NULL |
|
1071 PCRE_ERROR_BADMAGIC the "magic number" was not found |
|
1072 </pre> |
|
1073 If the <i>optptr</i> argument is not NULL, a copy of the options with which the |
|
1074 pattern was compiled is placed in the integer it points to (see |
|
1075 PCRE_INFO_OPTIONS above). |
|
1076 </P> |
|
1077 <P> |
|
1078 If the pattern is not anchored and the <i>firstcharptr</i> argument is not NULL, |
|
1079 it is used to pass back information about the first character of any matched |
|
1080 string (see PCRE_INFO_FIRSTBYTE above). |
|
1081 </P> |
|
1082 <br><a name="SEC13" href="#TOC1">REFERENCE COUNTS</a><br> |
|
1083 <P> |
|
1084 <b>int pcre_refcount(pcre *<i>code</i>, int <i>adjust</i>);</b> |
|
1085 </P> |
|
1086 <P> |
|
1087 The <b>pcre_refcount()</b> function is used to maintain a reference count in the |
|
1088 data block that contains a compiled pattern. It is provided for the benefit of |
|
1089 applications that operate in an object-oriented manner, where different parts |
|
1090 of the application may be using the same compiled pattern, but you want to free |
|
1091 the block when they are all done. |
|
1092 </P> |
|
1093 <P> |
|
1094 When a pattern is compiled, the reference count field is initialized to zero. |
|
1095 It is changed only by calling this function, whose action is to add the |
|
1096 <i>adjust</i> value (which may be positive or negative) to it. The yield of the |
|
1097 function is the new value. However, the value of the count is constrained to |
|
1098 lie between 0 and 65535, inclusive. If the new value is outside these limits, |
|
1099 it is forced to the appropriate limit value. |
|
1100 </P> |
|
1101 <P> |
|
1102 Except when it is zero, the reference count is not correctly preserved if a |
|
1103 pattern is compiled on one host and then transferred to a host whose byte-order |
|
1104 is different. (This seems a highly unlikely scenario.) |
|
1105 </P> |
|
1106 <br><a name="SEC14" href="#TOC1">MATCHING A PATTERN: THE TRADITIONAL FUNCTION</a><br> |
|
1107 <P> |
|
1108 <b>int pcre_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> |
|
1109 <b>const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b> |
|
1110 <b>int <i>options</i>, int *<i>ovector</i>, int <i>ovecsize</i>);</b> |
|
1111 </P> |
|
1112 <P> |
|
1113 The function <b>pcre_exec()</b> is called to match a subject string against a |
|
1114 compiled pattern, which is passed in the <i>code</i> argument. If the |
|
1115 pattern has been studied, the result of the study should be passed in the |
|
1116 <i>extra</i> argument. This function is the main matching facility of the |
|
1117 library, and it operates in a Perl-like manner. For specialist use there is |
|
1118 also an alternative matching function, which is described |
|
1119 <a href="#dfamatch">below</a> |
|
1120 in the section about the <b>pcre_dfa_exec()</b> function. |
|
1121 </P> |
|
1122 <P> |
|
1123 In most applications, the pattern will have been compiled (and optionally |
|
1124 studied) in the same process that calls <b>pcre_exec()</b>. However, it is |
|
1125 possible to save compiled patterns and study data, and then use them later |
|
1126 in different processes, possibly even on different hosts. For a discussion |
|
1127 about this, see the |
|
1128 <a href="pcreprecompile.html"><b>pcreprecompile</b></a> |
|
1129 documentation. |
|
1130 </P> |
|
1131 <P> |
|
1132 Here is an example of a simple call to <b>pcre_exec()</b>: |
|
1133 <pre> |
|
1134 int rc; |
|
1135 int ovector[30]; |
|
1136 rc = pcre_exec( |
|
1137 re, /* result of pcre_compile() */ |
|
1138 NULL, /* we didn't study the pattern */ |
|
1139 "some string", /* the subject string */ |
|
1140 11, /* the length of the subject string */ |
|
1141 0, /* start at offset 0 in the subject */ |
|
1142 0, /* default options */ |
|
1143 ovector, /* vector of integers for substring information */ |
|
1144 30); /* number of elements (NOT size in bytes) */ |
|
1145 <a name="extradata"></a></PRE> |
|
1146 </P> |
|
1147 <br><b> |
|
1148 Extra data for <b>pcre_exec()</b> |
|
1149 </b><br> |
|
1150 <P> |
|
1151 If the <i>extra</i> argument is not NULL, it must point to a <b>pcre_extra</b> |
|
1152 data block. The <b>pcre_study()</b> function returns such a block (when it |
|
1153 doesn't return NULL), but you can also create one for yourself, and pass |
|
1154 additional information in it. The <b>pcre_extra</b> block contains the following |
|
1155 fields (not necessarily in this order): |
|
1156 <pre> |
|
1157 unsigned long int <i>flags</i>; |
|
1158 void *<i>study_data</i>; |
|
1159 unsigned long int <i>match_limit</i>; |
|
1160 unsigned long int <i>match_limit_recursion</i>; |
|
1161 void *<i>callout_data</i>; |
|
1162 const unsigned char *<i>tables</i>; |
|
1163 </pre> |
|
1164 The <i>flags</i> field is a bitmap that specifies which of the other fields |
|
1165 are set. The flag bits are: |
|
1166 <pre> |
|
1167 PCRE_EXTRA_STUDY_DATA |
|
1168 PCRE_EXTRA_MATCH_LIMIT |
|
1169 PCRE_EXTRA_MATCH_LIMIT_RECURSION |
|
1170 PCRE_EXTRA_CALLOUT_DATA |
|
1171 PCRE_EXTRA_TABLES |
|
1172 </pre> |
|
1173 Other flag bits should be set to zero. The <i>study_data</i> field is set in the |
|
1174 <b>pcre_extra</b> block that is returned by <b>pcre_study()</b>, together with |
|
1175 the appropriate flag bit. You should not set this yourself, but you may add to |
|
1176 the block by setting the other fields and their corresponding flag bits. |
|
1177 </P> |
|
1178 <P> |
|
1179 The <i>match_limit</i> field provides a means of preventing PCRE from using up a |
|
1180 vast amount of resources when running patterns that are not going to match, |
|
1181 but which have a very large number of possibilities in their search trees. The |
|
1182 classic example is the use of nested unlimited repeats. |
|
1183 </P> |
|
1184 <P> |
|
1185 Internally, PCRE uses a function called <b>match()</b> which it calls repeatedly |
|
1186 (sometimes recursively). The limit set by <i>match_limit</i> is imposed on the |
|
1187 number of times this function is called during a match, which has the effect of |
|
1188 limiting the amount of backtracking that can take place. For patterns that are |
|
1189 not anchored, the count restarts from zero for each position in the subject |
|
1190 string. |
|
1191 </P> |
|
1192 <P> |
|
1193 The default value for the limit can be set when PCRE is built; the default |
|
1194 default is 10 million, which handles all but the most extreme cases. You can |
|
1195 override the default by suppling <b>pcre_exec()</b> with a <b>pcre_extra</b> |
|
1196 block in which <i>match_limit</i> is set, and PCRE_EXTRA_MATCH_LIMIT is set in |
|
1197 the <i>flags</i> field. If the limit is exceeded, <b>pcre_exec()</b> returns |
|
1198 PCRE_ERROR_MATCHLIMIT. |
|
1199 </P> |
|
1200 <P> |
|
1201 The <i>match_limit_recursion</i> field is similar to <i>match_limit</i>, but |
|
1202 instead of limiting the total number of times that <b>match()</b> is called, it |
|
1203 limits the depth of recursion. The recursion depth is a smaller number than the |
|
1204 total number of calls, because not all calls to <b>match()</b> are recursive. |
|
1205 This limit is of use only if it is set smaller than <i>match_limit</i>. |
|
1206 </P> |
|
1207 <P> |
|
1208 Limiting the recursion depth limits the amount of stack that can be used, or, |
|
1209 when PCRE has been compiled to use memory on the heap instead of the stack, the |
|
1210 amount of heap memory that can be used. |
|
1211 </P> |
|
1212 <P> |
|
1213 The default value for <i>match_limit_recursion</i> can be set when PCRE is |
|
1214 built; the default default is the same value as the default for |
|
1215 <i>match_limit</i>. You can override the default by suppling <b>pcre_exec()</b> |
|
1216 with a <b>pcre_extra</b> block in which <i>match_limit_recursion</i> is set, and |
|
1217 PCRE_EXTRA_MATCH_LIMIT_RECURSION is set in the <i>flags</i> field. If the limit |
|
1218 is exceeded, <b>pcre_exec()</b> returns PCRE_ERROR_RECURSIONLIMIT. |
|
1219 </P> |
|
1220 <P> |
|
1221 The <i>pcre_callout</i> field is used in conjunction with the "callout" feature, |
|
1222 which is described in the |
|
1223 <a href="pcrecallout.html"><b>pcrecallout</b></a> |
|
1224 documentation. |
|
1225 </P> |
|
1226 <P> |
|
1227 The <i>tables</i> field is used to pass a character tables pointer to |
|
1228 <b>pcre_exec()</b>; this overrides the value that is stored with the compiled |
|
1229 pattern. A non-NULL value is stored with the compiled pattern only if custom |
|
1230 tables were supplied to <b>pcre_compile()</b> via its <i>tableptr</i> argument. |
|
1231 If NULL is passed to <b>pcre_exec()</b> using this mechanism, it forces PCRE's |
|
1232 internal tables to be used. This facility is helpful when re-using patterns |
|
1233 that have been saved after compiling with an external set of tables, because |
|
1234 the external tables might be at a different address when <b>pcre_exec()</b> is |
|
1235 called. See the |
|
1236 <a href="pcreprecompile.html"><b>pcreprecompile</b></a> |
|
1237 documentation for a discussion of saving compiled patterns for later use. |
|
1238 <a name="execoptions"></a></P> |
|
1239 <br><b> |
|
1240 Option bits for <b>pcre_exec()</b> |
|
1241 </b><br> |
|
1242 <P> |
|
1243 The unused bits of the <i>options</i> argument for <b>pcre_exec()</b> must be |
|
1244 zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_<i>xxx</i>, |
|
1245 PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NO_UTF8_CHECK and PCRE_PARTIAL. |
|
1246 <pre> |
|
1247 PCRE_ANCHORED |
|
1248 </pre> |
|
1249 The PCRE_ANCHORED option limits <b>pcre_exec()</b> to matching at the first |
|
1250 matching position. If a pattern was compiled with PCRE_ANCHORED, or turned out |
|
1251 to be anchored by virtue of its contents, it cannot be made unachored at |
|
1252 matching time. |
|
1253 <pre> |
|
1254 PCRE_BSR_ANYCRLF |
|
1255 PCRE_BSR_UNICODE |
|
1256 </pre> |
|
1257 These options (which are mutually exclusive) control what the \R escape |
|
1258 sequence matches. The choice is either to match only CR, LF, or CRLF, or to |
|
1259 match any Unicode newline sequence. These options override the choice that was |
|
1260 made or defaulted when the pattern was compiled. |
|
1261 <pre> |
|
1262 PCRE_NEWLINE_CR |
|
1263 PCRE_NEWLINE_LF |
|
1264 PCRE_NEWLINE_CRLF |
|
1265 PCRE_NEWLINE_ANYCRLF |
|
1266 PCRE_NEWLINE_ANY |
|
1267 </pre> |
|
1268 These options override the newline definition that was chosen or defaulted when |
|
1269 the pattern was compiled. For details, see the description of |
|
1270 <b>pcre_compile()</b> above. During matching, the newline choice affects the |
|
1271 behaviour of the dot, circumflex, and dollar metacharacters. It may also alter |
|
1272 the way the match position is advanced after a match failure for an unanchored |
|
1273 pattern. |
|
1274 </P> |
|
1275 <P> |
|
1276 When PCRE_NEWLINE_CRLF, PCRE_NEWLINE_ANYCRLF, or PCRE_NEWLINE_ANY is set, and a |
|
1277 match attempt for an unanchored pattern fails when the current position is at a |
|
1278 CRLF sequence, and the pattern contains no explicit matches for CR or LF |
|
1279 characters, the match position is advanced by two characters instead of one, in |
|
1280 other words, to after the CRLF. |
|
1281 </P> |
|
1282 <P> |
|
1283 The above rule is a compromise that makes the most common cases work as |
|
1284 expected. For example, if the pattern is .+A (and the PCRE_DOTALL option is not |
|
1285 set), it does not match the string "\r\nA" because, after failing at the |
|
1286 start, it skips both the CR and the LF before retrying. However, the pattern |
|
1287 [\r\n]A does match that string, because it contains an explicit CR or LF |
|
1288 reference, and so advances only by one character after the first failure. |
|
1289 </P> |
|
1290 <P> |
|
1291 An explicit match for CR of LF is either a literal appearance of one of those |
|
1292 characters, or one of the \r or \n escape sequences. Implicit matches such as |
|
1293 [^X] do not count, nor does \s (which includes CR and LF in the characters |
|
1294 that it matches). |
|
1295 </P> |
|
1296 <P> |
|
1297 Notwithstanding the above, anomalous effects may still occur when CRLF is a |
|
1298 valid newline sequence and explicit \r or \n escapes appear in the pattern. |
|
1299 <pre> |
|
1300 PCRE_NOTBOL |
|
1301 </pre> |
|
1302 This option specifies that first character of the subject string is not the |
|
1303 beginning of a line, so the circumflex metacharacter should not match before |
|
1304 it. Setting this without PCRE_MULTILINE (at compile time) causes circumflex |
|
1305 never to match. This option affects only the behaviour of the circumflex |
|
1306 metacharacter. It does not affect \A. |
|
1307 <pre> |
|
1308 PCRE_NOTEOL |
|
1309 </pre> |
|
1310 This option specifies that the end of the subject string is not the end of a |
|
1311 line, so the dollar metacharacter should not match it nor (except in multiline |
|
1312 mode) a newline immediately before it. Setting this without PCRE_MULTILINE (at |
|
1313 compile time) causes dollar never to match. This option affects only the |
|
1314 behaviour of the dollar metacharacter. It does not affect \Z or \z. |
|
1315 <pre> |
|
1316 PCRE_NOTEMPTY |
|
1317 </pre> |
|
1318 An empty string is not considered to be a valid match if this option is set. If |
|
1319 there are alternatives in the pattern, they are tried. If all the alternatives |
|
1320 match the empty string, the entire match fails. For example, if the pattern |
|
1321 <pre> |
|
1322 a?b? |
|
1323 </pre> |
|
1324 is applied to a string not beginning with "a" or "b", it matches the empty |
|
1325 string at the start of the subject. With PCRE_NOTEMPTY set, this match is not |
|
1326 valid, so PCRE searches further into the string for occurrences of "a" or "b". |
|
1327 </P> |
|
1328 <P> |
|
1329 Perl has no direct equivalent of PCRE_NOTEMPTY, but it does make a special case |
|
1330 of a pattern match of the empty string within its <b>split()</b> function, and |
|
1331 when using the /g modifier. It is possible to emulate Perl's behaviour after |
|
1332 matching a null string by first trying the match again at the same offset with |
|
1333 PCRE_NOTEMPTY and PCRE_ANCHORED, and then if that fails by advancing the |
|
1334 starting offset (see below) and trying an ordinary match again. There is some |
|
1335 code that demonstrates how to do this in the <i>pcredemo.c</i> sample program. |
|
1336 <pre> |
|
1337 PCRE_NO_UTF8_CHECK |
|
1338 </pre> |
|
1339 When PCRE_UTF8 is set at compile time, the validity of the subject as a UTF-8 |
|
1340 string is automatically checked when <b>pcre_exec()</b> is subsequently called. |
|
1341 The value of <i>startoffset</i> is also checked to ensure that it points to the |
|
1342 start of a UTF-8 character. There is a discussion about the validity of UTF-8 |
|
1343 strings in the |
|
1344 <a href="pcre.html#utf8strings">section on UTF-8 support</a> |
|
1345 in the main |
|
1346 <a href="pcre.html"><b>pcre</b></a> |
|
1347 page. If an invalid UTF-8 sequence of bytes is found, <b>pcre_exec()</b> returns |
|
1348 the error PCRE_ERROR_BADUTF8. If <i>startoffset</i> contains an invalid value, |
|
1349 PCRE_ERROR_BADUTF8_OFFSET is returned. |
|
1350 </P> |
|
1351 <P> |
|
1352 If you already know that your subject is valid, and you want to skip these |
|
1353 checks for performance reasons, you can set the PCRE_NO_UTF8_CHECK option when |
|
1354 calling <b>pcre_exec()</b>. You might want to do this for the second and |
|
1355 subsequent calls to <b>pcre_exec()</b> if you are making repeated calls to find |
|
1356 all the matches in a single subject string. However, you should be sure that |
|
1357 the value of <i>startoffset</i> points to the start of a UTF-8 character. When |
|
1358 PCRE_NO_UTF8_CHECK is set, the effect of passing an invalid UTF-8 string as a |
|
1359 subject, or a value of <i>startoffset</i> that does not point to the start of a |
|
1360 UTF-8 character, is undefined. Your program may crash. |
|
1361 <pre> |
|
1362 PCRE_PARTIAL |
|
1363 </pre> |
|
1364 This option turns on the partial matching feature. If the subject string fails |
|
1365 to match the pattern, but at some point during the matching process the end of |
|
1366 the subject was reached (that is, the subject partially matches the pattern and |
|
1367 the failure to match occurred only because there were not enough subject |
|
1368 characters), <b>pcre_exec()</b> returns PCRE_ERROR_PARTIAL instead of |
|
1369 PCRE_ERROR_NOMATCH. When PCRE_PARTIAL is used, there are restrictions on what |
|
1370 may appear in the pattern. These are discussed in the |
|
1371 <a href="pcrepartial.html"><b>pcrepartial</b></a> |
|
1372 documentation. |
|
1373 </P> |
|
1374 <br><b> |
|
1375 The string to be matched by <b>pcre_exec()</b> |
|
1376 </b><br> |
|
1377 <P> |
|
1378 The subject string is passed to <b>pcre_exec()</b> as a pointer in |
|
1379 <i>subject</i>, a length (in bytes) in <i>length</i>, and a starting byte offset |
|
1380 in <i>startoffset</i>. In UTF-8 mode, the byte offset must point to the start of |
|
1381 a UTF-8 character. Unlike the pattern string, the subject may contain binary |
|
1382 zero bytes. When the starting offset is zero, the search for a match starts at |
|
1383 the beginning of the subject, and this is by far the most common case. |
|
1384 </P> |
|
1385 <P> |
|
1386 A non-zero starting offset is useful when searching for another match in the |
|
1387 same subject by calling <b>pcre_exec()</b> again after a previous success. |
|
1388 Setting <i>startoffset</i> differs from just passing over a shortened string and |
|
1389 setting PCRE_NOTBOL in the case of a pattern that begins with any kind of |
|
1390 lookbehind. For example, consider the pattern |
|
1391 <pre> |
|
1392 \Biss\B |
|
1393 </pre> |
|
1394 which finds occurrences of "iss" in the middle of words. (\B matches only if |
|
1395 the current position in the subject is not a word boundary.) When applied to |
|
1396 the string "Mississipi" the first call to <b>pcre_exec()</b> finds the first |
|
1397 occurrence. If <b>pcre_exec()</b> is called again with just the remainder of the |
|
1398 subject, namely "issipi", it does not match, because \B is always false at the |
|
1399 start of the subject, which is deemed to be a word boundary. However, if |
|
1400 <b>pcre_exec()</b> is passed the entire string again, but with <i>startoffset</i> |
|
1401 set to 4, it finds the second occurrence of "iss" because it is able to look |
|
1402 behind the starting point to discover that it is preceded by a letter. |
|
1403 </P> |
|
1404 <P> |
|
1405 If a non-zero starting offset is passed when the pattern is anchored, one |
|
1406 attempt to match at the given offset is made. This can only succeed if the |
|
1407 pattern does not require the match to be at the start of the subject. |
|
1408 </P> |
|
1409 <br><b> |
|
1410 How <b>pcre_exec()</b> returns captured substrings |
|
1411 </b><br> |
|
1412 <P> |
|
1413 In general, a pattern matches a certain portion of the subject, and in |
|
1414 addition, further substrings from the subject may be picked out by parts of the |
|
1415 pattern. Following the usage in Jeffrey Friedl's book, this is called |
|
1416 "capturing" in what follows, and the phrase "capturing subpattern" is used for |
|
1417 a fragment of a pattern that picks out a substring. PCRE supports several other |
|
1418 kinds of parenthesized subpattern that do not cause substrings to be captured. |
|
1419 </P> |
|
1420 <P> |
|
1421 Captured substrings are returned to the caller via a vector of integers whose |
|
1422 address is passed in <i>ovector</i>. The number of elements in the vector is |
|
1423 passed in <i>ovecsize</i>, which must be a non-negative number. <b>Note</b>: this |
|
1424 argument is NOT the size of <i>ovector</i> in bytes. |
|
1425 </P> |
|
1426 <P> |
|
1427 The first two-thirds of the vector is used to pass back captured substrings, |
|
1428 each substring using a pair of integers. The remaining third of the vector is |
|
1429 used as workspace by <b>pcre_exec()</b> while matching capturing subpatterns, |
|
1430 and is not available for passing back information. The number passed in |
|
1431 <i>ovecsize</i> should always be a multiple of three. If it is not, it is |
|
1432 rounded down. |
|
1433 </P> |
|
1434 <P> |
|
1435 When a match is successful, information about captured substrings is returned |
|
1436 in pairs of integers, starting at the beginning of <i>ovector</i>, and |
|
1437 continuing up to two-thirds of its length at the most. The first element of |
|
1438 each pair is set to the byte offset of the first character in a substring, and |
|
1439 the second is set to the byte offset of the first character after the end of a |
|
1440 substring. <b>Note</b>: these values are always byte offsets, even in UTF-8 |
|
1441 mode. They are not character counts. |
|
1442 </P> |
|
1443 <P> |
|
1444 The first pair of integers, <i>ovector[0]</i> and <i>ovector[1]</i>, identify the |
|
1445 portion of the subject string matched by the entire pattern. The next pair is |
|
1446 used for the first capturing subpattern, and so on. The value returned by |
|
1447 <b>pcre_exec()</b> is one more than the highest numbered pair that has been set. |
|
1448 For example, if two substrings have been captured, the returned value is 3. If |
|
1449 there are no capturing subpatterns, the return value from a successful match is |
|
1450 1, indicating that just the first pair of offsets has been set. |
|
1451 </P> |
|
1452 <P> |
|
1453 If a capturing subpattern is matched repeatedly, it is the last portion of the |
|
1454 string that it matched that is returned. |
|
1455 </P> |
|
1456 <P> |
|
1457 If the vector is too small to hold all the captured substring offsets, it is |
|
1458 used as far as possible (up to two-thirds of its length), and the function |
|
1459 returns a value of zero. If the substring offsets are not of interest, |
|
1460 <b>pcre_exec()</b> may be called with <i>ovector</i> passed as NULL and |
|
1461 <i>ovecsize</i> as zero. However, if the pattern contains back references and |
|
1462 the <i>ovector</i> is not big enough to remember the related substrings, PCRE |
|
1463 has to get additional memory for use during matching. Thus it is usually |
|
1464 advisable to supply an <i>ovector</i>. |
|
1465 </P> |
|
1466 <P> |
|
1467 The <b>pcre_info()</b> function can be used to find out how many capturing |
|
1468 subpatterns there are in a compiled pattern. The smallest size for |
|
1469 <i>ovector</i> that will allow for <i>n</i> captured substrings, in addition to |
|
1470 the offsets of the substring matched by the whole pattern, is (<i>n</i>+1)*3. |
|
1471 </P> |
|
1472 <P> |
|
1473 It is possible for capturing subpattern number <i>n+1</i> to match some part of |
|
1474 the subject when subpattern <i>n</i> has not been used at all. For example, if |
|
1475 the string "abc" is matched against the pattern (a|(z))(bc) the return from the |
|
1476 function is 4, and subpatterns 1 and 3 are matched, but 2 is not. When this |
|
1477 happens, both values in the offset pairs corresponding to unused subpatterns |
|
1478 are set to -1. |
|
1479 </P> |
|
1480 <P> |
|
1481 Offset values that correspond to unused subpatterns at the end of the |
|
1482 expression are also set to -1. For example, if the string "abc" is matched |
|
1483 against the pattern (abc)(x(yz)?)? subpatterns 2 and 3 are not matched. The |
|
1484 return from the function is 2, because the highest used capturing subpattern |
|
1485 number is 1. However, you can refer to the offsets for the second and third |
|
1486 capturing subpatterns if you wish (assuming the vector is large enough, of |
|
1487 course). |
|
1488 </P> |
|
1489 <P> |
|
1490 Some convenience functions are provided for extracting the captured substrings |
|
1491 as separate strings. These are described below. |
|
1492 <a name="errorlist"></a></P> |
|
1493 <br><b> |
|
1494 Error return values from <b>pcre_exec()</b> |
|
1495 </b><br> |
|
1496 <P> |
|
1497 If <b>pcre_exec()</b> fails, it returns a negative number. The following are |
|
1498 defined in the header file: |
|
1499 <pre> |
|
1500 PCRE_ERROR_NOMATCH (-1) |
|
1501 </pre> |
|
1502 The subject string did not match the pattern. |
|
1503 <pre> |
|
1504 PCRE_ERROR_NULL (-2) |
|
1505 </pre> |
|
1506 Either <i>code</i> or <i>subject</i> was passed as NULL, or <i>ovector</i> was |
|
1507 NULL and <i>ovecsize</i> was not zero. |
|
1508 <pre> |
|
1509 PCRE_ERROR_BADOPTION (-3) |
|
1510 </pre> |
|
1511 An unrecognized bit was set in the <i>options</i> argument. |
|
1512 <pre> |
|
1513 PCRE_ERROR_BADMAGIC (-4) |
|
1514 </pre> |
|
1515 PCRE stores a 4-byte "magic number" at the start of the compiled code, to catch |
|
1516 the case when it is passed a junk pointer and to detect when a pattern that was |
|
1517 compiled in an environment of one endianness is run in an environment with the |
|
1518 other endianness. This is the error that PCRE gives when the magic number is |
|
1519 not present. |
|
1520 <pre> |
|
1521 PCRE_ERROR_UNKNOWN_OPCODE (-5) |
|
1522 </pre> |
|
1523 While running the pattern match, an unknown item was encountered in the |
|
1524 compiled pattern. This error could be caused by a bug in PCRE or by overwriting |
|
1525 of the compiled pattern. |
|
1526 <pre> |
|
1527 PCRE_ERROR_NOMEMORY (-6) |
|
1528 </pre> |
|
1529 If a pattern contains back references, but the <i>ovector</i> that is passed to |
|
1530 <b>pcre_exec()</b> is not big enough to remember the referenced substrings, PCRE |
|
1531 gets a block of memory at the start of matching to use for this purpose. If the |
|
1532 call via <b>pcre_malloc()</b> fails, this error is given. The memory is |
|
1533 automatically freed at the end of matching. |
|
1534 <pre> |
|
1535 PCRE_ERROR_NOSUBSTRING (-7) |
|
1536 </pre> |
|
1537 This error is used by the <b>pcre_copy_substring()</b>, |
|
1538 <b>pcre_get_substring()</b>, and <b>pcre_get_substring_list()</b> functions (see |
|
1539 below). It is never returned by <b>pcre_exec()</b>. |
|
1540 <pre> |
|
1541 PCRE_ERROR_MATCHLIMIT (-8) |
|
1542 </pre> |
|
1543 The backtracking limit, as specified by the <i>match_limit</i> field in a |
|
1544 <b>pcre_extra</b> structure (or defaulted) was reached. See the description |
|
1545 above. |
|
1546 <pre> |
|
1547 PCRE_ERROR_CALLOUT (-9) |
|
1548 </pre> |
|
1549 This error is never generated by <b>pcre_exec()</b> itself. It is provided for |
|
1550 use by callout functions that want to yield a distinctive error code. See the |
|
1551 <a href="pcrecallout.html"><b>pcrecallout</b></a> |
|
1552 documentation for details. |
|
1553 <pre> |
|
1554 PCRE_ERROR_BADUTF8 (-10) |
|
1555 </pre> |
|
1556 A string that contains an invalid UTF-8 byte sequence was passed as a subject. |
|
1557 <pre> |
|
1558 PCRE_ERROR_BADUTF8_OFFSET (-11) |
|
1559 </pre> |
|
1560 The UTF-8 byte sequence that was passed as a subject was valid, but the value |
|
1561 of <i>startoffset</i> did not point to the beginning of a UTF-8 character. |
|
1562 <pre> |
|
1563 PCRE_ERROR_PARTIAL (-12) |
|
1564 </pre> |
|
1565 The subject string did not match, but it did match partially. See the |
|
1566 <a href="pcrepartial.html"><b>pcrepartial</b></a> |
|
1567 documentation for details of partial matching. |
|
1568 <pre> |
|
1569 PCRE_ERROR_BADPARTIAL (-13) |
|
1570 </pre> |
|
1571 The PCRE_PARTIAL option was used with a compiled pattern containing items that |
|
1572 are not supported for partial matching. See the |
|
1573 <a href="pcrepartial.html"><b>pcrepartial</b></a> |
|
1574 documentation for details of partial matching. |
|
1575 <pre> |
|
1576 PCRE_ERROR_INTERNAL (-14) |
|
1577 </pre> |
|
1578 An unexpected internal error has occurred. This error could be caused by a bug |
|
1579 in PCRE or by overwriting of the compiled pattern. |
|
1580 <pre> |
|
1581 PCRE_ERROR_BADCOUNT (-15) |
|
1582 </pre> |
|
1583 This error is given if the value of the <i>ovecsize</i> argument is negative. |
|
1584 <pre> |
|
1585 PCRE_ERROR_RECURSIONLIMIT (-21) |
|
1586 </pre> |
|
1587 The internal recursion limit, as specified by the <i>match_limit_recursion</i> |
|
1588 field in a <b>pcre_extra</b> structure (or defaulted) was reached. See the |
|
1589 description above. |
|
1590 <pre> |
|
1591 PCRE_ERROR_BADNEWLINE (-23) |
|
1592 </pre> |
|
1593 An invalid combination of PCRE_NEWLINE_<i>xxx</i> options was given. |
|
1594 </P> |
|
1595 <P> |
|
1596 Error numbers -16 to -20 and -22 are not used by <b>pcre_exec()</b>. |
|
1597 </P> |
|
1598 <br><a name="SEC15" href="#TOC1">EXTRACTING CAPTURED SUBSTRINGS BY NUMBER</a><br> |
|
1599 <P> |
|
1600 <b>int pcre_copy_substring(const char *<i>subject</i>, int *<i>ovector</i>,</b> |
|
1601 <b>int <i>stringcount</i>, int <i>stringnumber</i>, char *<i>buffer</i>,</b> |
|
1602 <b>int <i>buffersize</i>);</b> |
|
1603 </P> |
|
1604 <P> |
|
1605 <b>int pcre_get_substring(const char *<i>subject</i>, int *<i>ovector</i>,</b> |
|
1606 <b>int <i>stringcount</i>, int <i>stringnumber</i>,</b> |
|
1607 <b>const char **<i>stringptr</i>);</b> |
|
1608 </P> |
|
1609 <P> |
|
1610 <b>int pcre_get_substring_list(const char *<i>subject</i>,</b> |
|
1611 <b>int *<i>ovector</i>, int <i>stringcount</i>, const char ***<i>listptr</i>);</b> |
|
1612 </P> |
|
1613 <P> |
|
1614 Captured substrings can be accessed directly by using the offsets returned by |
|
1615 <b>pcre_exec()</b> in <i>ovector</i>. For convenience, the functions |
|
1616 <b>pcre_copy_substring()</b>, <b>pcre_get_substring()</b>, and |
|
1617 <b>pcre_get_substring_list()</b> are provided for extracting captured substrings |
|
1618 as new, separate, zero-terminated strings. These functions identify substrings |
|
1619 by number. The next section describes functions for extracting named |
|
1620 substrings. |
|
1621 </P> |
|
1622 <P> |
|
1623 A substring that contains a binary zero is correctly extracted and has a |
|
1624 further zero added on the end, but the result is not, of course, a C string. |
|
1625 However, you can process such a string by referring to the length that is |
|
1626 returned by <b>pcre_copy_substring()</b> and <b>pcre_get_substring()</b>. |
|
1627 Unfortunately, the interface to <b>pcre_get_substring_list()</b> is not adequate |
|
1628 for handling strings containing binary zeros, because the end of the final |
|
1629 string is not independently indicated. |
|
1630 </P> |
|
1631 <P> |
|
1632 The first three arguments are the same for all three of these functions: |
|
1633 <i>subject</i> is the subject string that has just been successfully matched, |
|
1634 <i>ovector</i> is a pointer to the vector of integer offsets that was passed to |
|
1635 <b>pcre_exec()</b>, and <i>stringcount</i> is the number of substrings that were |
|
1636 captured by the match, including the substring that matched the entire regular |
|
1637 expression. This is the value returned by <b>pcre_exec()</b> if it is greater |
|
1638 than zero. If <b>pcre_exec()</b> returned zero, indicating that it ran out of |
|
1639 space in <i>ovector</i>, the value passed as <i>stringcount</i> should be the |
|
1640 number of elements in the vector divided by three. |
|
1641 </P> |
|
1642 <P> |
|
1643 The functions <b>pcre_copy_substring()</b> and <b>pcre_get_substring()</b> |
|
1644 extract a single substring, whose number is given as <i>stringnumber</i>. A |
|
1645 value of zero extracts the substring that matched the entire pattern, whereas |
|
1646 higher values extract the captured substrings. For <b>pcre_copy_substring()</b>, |
|
1647 the string is placed in <i>buffer</i>, whose length is given by |
|
1648 <i>buffersize</i>, while for <b>pcre_get_substring()</b> a new block of memory is |
|
1649 obtained via <b>pcre_malloc</b>, and its address is returned via |
|
1650 <i>stringptr</i>. The yield of the function is the length of the string, not |
|
1651 including the terminating zero, or one of these error codes: |
|
1652 <pre> |
|
1653 PCRE_ERROR_NOMEMORY (-6) |
|
1654 </pre> |
|
1655 The buffer was too small for <b>pcre_copy_substring()</b>, or the attempt to get |
|
1656 memory failed for <b>pcre_get_substring()</b>. |
|
1657 <pre> |
|
1658 PCRE_ERROR_NOSUBSTRING (-7) |
|
1659 </pre> |
|
1660 There is no substring whose number is <i>stringnumber</i>. |
|
1661 </P> |
|
1662 <P> |
|
1663 The <b>pcre_get_substring_list()</b> function extracts all available substrings |
|
1664 and builds a list of pointers to them. All this is done in a single block of |
|
1665 memory that is obtained via <b>pcre_malloc</b>. The address of the memory block |
|
1666 is returned via <i>listptr</i>, which is also the start of the list of string |
|
1667 pointers. The end of the list is marked by a NULL pointer. The yield of the |
|
1668 function is zero if all went well, or the error code |
|
1669 <pre> |
|
1670 PCRE_ERROR_NOMEMORY (-6) |
|
1671 </pre> |
|
1672 if the attempt to get the memory block failed. |
|
1673 </P> |
|
1674 <P> |
|
1675 When any of these functions encounter a substring that is unset, which can |
|
1676 happen when capturing subpattern number <i>n+1</i> matches some part of the |
|
1677 subject, but subpattern <i>n</i> has not been used at all, they return an empty |
|
1678 string. This can be distinguished from a genuine zero-length substring by |
|
1679 inspecting the appropriate offset in <i>ovector</i>, which is negative for unset |
|
1680 substrings. |
|
1681 </P> |
|
1682 <P> |
|
1683 The two convenience functions <b>pcre_free_substring()</b> and |
|
1684 <b>pcre_free_substring_list()</b> can be used to free the memory returned by |
|
1685 a previous call of <b>pcre_get_substring()</b> or |
|
1686 <b>pcre_get_substring_list()</b>, respectively. They do nothing more than call |
|
1687 the function pointed to by <b>pcre_free</b>, which of course could be called |
|
1688 directly from a C program. However, PCRE is used in some situations where it is |
|
1689 linked via a special interface to another programming language that cannot use |
|
1690 <b>pcre_free</b> directly; it is for these cases that the functions are |
|
1691 provided. |
|
1692 </P> |
|
1693 <br><a name="SEC16" href="#TOC1">EXTRACTING CAPTURED SUBSTRINGS BY NAME</a><br> |
|
1694 <P> |
|
1695 <b>int pcre_get_stringnumber(const pcre *<i>code</i>,</b> |
|
1696 <b>const char *<i>name</i>);</b> |
|
1697 </P> |
|
1698 <P> |
|
1699 <b>int pcre_copy_named_substring(const pcre *<i>code</i>,</b> |
|
1700 <b>const char *<i>subject</i>, int *<i>ovector</i>,</b> |
|
1701 <b>int <i>stringcount</i>, const char *<i>stringname</i>,</b> |
|
1702 <b>char *<i>buffer</i>, int <i>buffersize</i>);</b> |
|
1703 </P> |
|
1704 <P> |
|
1705 <b>int pcre_get_named_substring(const pcre *<i>code</i>,</b> |
|
1706 <b>const char *<i>subject</i>, int *<i>ovector</i>,</b> |
|
1707 <b>int <i>stringcount</i>, const char *<i>stringname</i>,</b> |
|
1708 <b>const char **<i>stringptr</i>);</b> |
|
1709 </P> |
|
1710 <P> |
|
1711 To extract a substring by name, you first have to find associated number. |
|
1712 For example, for this pattern |
|
1713 <pre> |
|
1714 (a+)b(?<xxx>\d+)... |
|
1715 </pre> |
|
1716 the number of the subpattern called "xxx" is 2. If the name is known to be |
|
1717 unique (PCRE_DUPNAMES was not set), you can find the number from the name by |
|
1718 calling <b>pcre_get_stringnumber()</b>. The first argument is the compiled |
|
1719 pattern, and the second is the name. The yield of the function is the |
|
1720 subpattern number, or PCRE_ERROR_NOSUBSTRING (-7) if there is no subpattern of |
|
1721 that name. |
|
1722 </P> |
|
1723 <P> |
|
1724 Given the number, you can extract the substring directly, or use one of the |
|
1725 functions described in the previous section. For convenience, there are also |
|
1726 two functions that do the whole job. |
|
1727 </P> |
|
1728 <P> |
|
1729 Most of the arguments of <b>pcre_copy_named_substring()</b> and |
|
1730 <b>pcre_get_named_substring()</b> are the same as those for the similarly named |
|
1731 functions that extract by number. As these are described in the previous |
|
1732 section, they are not re-described here. There are just two differences: |
|
1733 </P> |
|
1734 <P> |
|
1735 First, instead of a substring number, a substring name is given. Second, there |
|
1736 is an extra argument, given at the start, which is a pointer to the compiled |
|
1737 pattern. This is needed in order to gain access to the name-to-number |
|
1738 translation table. |
|
1739 </P> |
|
1740 <P> |
|
1741 These functions call <b>pcre_get_stringnumber()</b>, and if it succeeds, they |
|
1742 then call <b>pcre_copy_substring()</b> or <b>pcre_get_substring()</b>, as |
|
1743 appropriate. <b>NOTE:</b> If PCRE_DUPNAMES is set and there are duplicate names, |
|
1744 the behaviour may not be what you want (see the next section). |
|
1745 </P> |
|
1746 <br><a name="SEC17" href="#TOC1">DUPLICATE SUBPATTERN NAMES</a><br> |
|
1747 <P> |
|
1748 <b>int pcre_get_stringtable_entries(const pcre *<i>code</i>,</b> |
|
1749 <b>const char *<i>name</i>, char **<i>first</i>, char **<i>last</i>);</b> |
|
1750 </P> |
|
1751 <P> |
|
1752 When a pattern is compiled with the PCRE_DUPNAMES option, names for subpatterns |
|
1753 are not required to be unique. Normally, patterns with duplicate names are such |
|
1754 that in any one match, only one of the named subpatterns participates. An |
|
1755 example is shown in the |
|
1756 <a href="pcrepattern.html"><b>pcrepattern</b></a> |
|
1757 documentation. |
|
1758 </P> |
|
1759 <P> |
|
1760 When duplicates are present, <b>pcre_copy_named_substring()</b> and |
|
1761 <b>pcre_get_named_substring()</b> return the first substring corresponding to |
|
1762 the given name that is set. If none are set, PCRE_ERROR_NOSUBSTRING (-7) is |
|
1763 returned; no data is returned. The <b>pcre_get_stringnumber()</b> function |
|
1764 returns one of the numbers that are associated with the name, but it is not |
|
1765 defined which it is. |
|
1766 </P> |
|
1767 <P> |
|
1768 If you want to get full details of all captured substrings for a given name, |
|
1769 you must use the <b>pcre_get_stringtable_entries()</b> function. The first |
|
1770 argument is the compiled pattern, and the second is the name. The third and |
|
1771 fourth are pointers to variables which are updated by the function. After it |
|
1772 has run, they point to the first and last entries in the name-to-number table |
|
1773 for the given name. The function itself returns the length of each entry, or |
|
1774 PCRE_ERROR_NOSUBSTRING (-7) if there are none. The format of the table is |
|
1775 described above in the section entitled <i>Information about a pattern</i>. |
|
1776 Given all the relevant entries for the name, you can extract each of their |
|
1777 numbers, and hence the captured data, if any. |
|
1778 </P> |
|
1779 <br><a name="SEC18" href="#TOC1">FINDING ALL POSSIBLE MATCHES</a><br> |
|
1780 <P> |
|
1781 The traditional matching function uses a similar algorithm to Perl, which stops |
|
1782 when it finds the first match, starting at a given point in the subject. If you |
|
1783 want to find all possible matches, or the longest possible match, consider |
|
1784 using the alternative matching function (see below) instead. If you cannot use |
|
1785 the alternative function, but still need to find all possible matches, you |
|
1786 can kludge it up by making use of the callout facility, which is described in |
|
1787 the |
|
1788 <a href="pcrecallout.html"><b>pcrecallout</b></a> |
|
1789 documentation. |
|
1790 </P> |
|
1791 <P> |
|
1792 What you have to do is to insert a callout right at the end of the pattern. |
|
1793 When your callout function is called, extract and save the current matched |
|
1794 substring. Then return 1, which forces <b>pcre_exec()</b> to backtrack and try |
|
1795 other alternatives. Ultimately, when it runs out of matches, <b>pcre_exec()</b> |
|
1796 will yield PCRE_ERROR_NOMATCH. |
|
1797 <a name="dfamatch"></a></P> |
|
1798 <br><a name="SEC19" href="#TOC1">MATCHING A PATTERN: THE ALTERNATIVE FUNCTION</a><br> |
|
1799 <P> |
|
1800 <b>int pcre_dfa_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b> |
|
1801 <b>const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b> |
|
1802 <b>int <i>options</i>, int *<i>ovector</i>, int <i>ovecsize</i>,</b> |
|
1803 <b>int *<i>workspace</i>, int <i>wscount</i>);</b> |
|
1804 </P> |
|
1805 <P> |
|
1806 The function <b>pcre_dfa_exec()</b> is called to match a subject string against |
|
1807 a compiled pattern, using a matching algorithm that scans the subject string |
|
1808 just once, and does not backtrack. This has different characteristics to the |
|
1809 normal algorithm, and is not compatible with Perl. Some of the features of PCRE |
|
1810 patterns are not supported. Nevertheless, there are times when this kind of |
|
1811 matching can be useful. For a discussion of the two matching algorithms, see |
|
1812 the |
|
1813 <a href="pcrematching.html"><b>pcrematching</b></a> |
|
1814 documentation. |
|
1815 </P> |
|
1816 <P> |
|
1817 The arguments for the <b>pcre_dfa_exec()</b> function are the same as for |
|
1818 <b>pcre_exec()</b>, plus two extras. The <i>ovector</i> argument is used in a |
|
1819 different way, and this is described below. The other common arguments are used |
|
1820 in the same way as for <b>pcre_exec()</b>, so their description is not repeated |
|
1821 here. |
|
1822 </P> |
|
1823 <P> |
|
1824 The two additional arguments provide workspace for the function. The workspace |
|
1825 vector should contain at least 20 elements. It is used for keeping track of |
|
1826 multiple paths through the pattern tree. More workspace will be needed for |
|
1827 patterns and subjects where there are a lot of potential matches. |
|
1828 </P> |
|
1829 <P> |
|
1830 Here is an example of a simple call to <b>pcre_dfa_exec()</b>: |
|
1831 <pre> |
|
1832 int rc; |
|
1833 int ovector[10]; |
|
1834 int wspace[20]; |
|
1835 rc = pcre_dfa_exec( |
|
1836 re, /* result of pcre_compile() */ |
|
1837 NULL, /* we didn't study the pattern */ |
|
1838 "some string", /* the subject string */ |
|
1839 11, /* the length of the subject string */ |
|
1840 0, /* start at offset 0 in the subject */ |
|
1841 0, /* default options */ |
|
1842 ovector, /* vector of integers for substring information */ |
|
1843 10, /* number of elements (NOT size in bytes) */ |
|
1844 wspace, /* working space vector */ |
|
1845 20); /* number of elements (NOT size in bytes) */ |
|
1846 </PRE> |
|
1847 </P> |
|
1848 <br><b> |
|
1849 Option bits for <b>pcre_dfa_exec()</b> |
|
1850 </b><br> |
|
1851 <P> |
|
1852 The unused bits of the <i>options</i> argument for <b>pcre_dfa_exec()</b> must be |
|
1853 zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_<i>xxx</i>, |
|
1854 PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NO_UTF8_CHECK, PCRE_PARTIAL, |
|
1855 PCRE_DFA_SHORTEST, and PCRE_DFA_RESTART. All but the last three of these are |
|
1856 the same as for <b>pcre_exec()</b>, so their description is not repeated here. |
|
1857 <pre> |
|
1858 PCRE_PARTIAL |
|
1859 </pre> |
|
1860 This has the same general effect as it does for <b>pcre_exec()</b>, but the |
|
1861 details are slightly different. When PCRE_PARTIAL is set for |
|
1862 <b>pcre_dfa_exec()</b>, the return code PCRE_ERROR_NOMATCH is converted into |
|
1863 PCRE_ERROR_PARTIAL if the end of the subject is reached, there have been no |
|
1864 complete matches, but there is still at least one matching possibility. The |
|
1865 portion of the string that provided the partial match is set as the first |
|
1866 matching string. |
|
1867 <pre> |
|
1868 PCRE_DFA_SHORTEST |
|
1869 </pre> |
|
1870 Setting the PCRE_DFA_SHORTEST option causes the matching algorithm to stop as |
|
1871 soon as it has found one match. Because of the way the alternative algorithm |
|
1872 works, this is necessarily the shortest possible match at the first possible |
|
1873 matching point in the subject string. |
|
1874 <pre> |
|
1875 PCRE_DFA_RESTART |
|
1876 </pre> |
|
1877 When <b>pcre_dfa_exec()</b> is called with the PCRE_PARTIAL option, and returns |
|
1878 a partial match, it is possible to call it again, with additional subject |
|
1879 characters, and have it continue with the same match. The PCRE_DFA_RESTART |
|
1880 option requests this action; when it is set, the <i>workspace</i> and |
|
1881 <i>wscount</i> options must reference the same vector as before because data |
|
1882 about the match so far is left in them after a partial match. There is more |
|
1883 discussion of this facility in the |
|
1884 <a href="pcrepartial.html"><b>pcrepartial</b></a> |
|
1885 documentation. |
|
1886 </P> |
|
1887 <br><b> |
|
1888 Successful returns from <b>pcre_dfa_exec()</b> |
|
1889 </b><br> |
|
1890 <P> |
|
1891 When <b>pcre_dfa_exec()</b> succeeds, it may have matched more than one |
|
1892 substring in the subject. Note, however, that all the matches from one run of |
|
1893 the function start at the same point in the subject. The shorter matches are |
|
1894 all initial substrings of the longer matches. For example, if the pattern |
|
1895 <pre> |
|
1896 <.*> |
|
1897 </pre> |
|
1898 is matched against the string |
|
1899 <pre> |
|
1900 This is <something> <something else> <something further> no more |
|
1901 </pre> |
|
1902 the three matched strings are |
|
1903 <pre> |
|
1904 <something> |
|
1905 <something> <something else> |
|
1906 <something> <something else> <something further> |
|
1907 </pre> |
|
1908 On success, the yield of the function is a number greater than zero, which is |
|
1909 the number of matched substrings. The substrings themselves are returned in |
|
1910 <i>ovector</i>. Each string uses two elements; the first is the offset to the |
|
1911 start, and the second is the offset to the end. In fact, all the strings have |
|
1912 the same start offset. (Space could have been saved by giving this only once, |
|
1913 but it was decided to retain some compatibility with the way <b>pcre_exec()</b> |
|
1914 returns data, even though the meaning of the strings is different.) |
|
1915 </P> |
|
1916 <P> |
|
1917 The strings are returned in reverse order of length; that is, the longest |
|
1918 matching string is given first. If there were too many matches to fit into |
|
1919 <i>ovector</i>, the yield of the function is zero, and the vector is filled with |
|
1920 the longest matches. |
|
1921 </P> |
|
1922 <br><b> |
|
1923 Error returns from <b>pcre_dfa_exec()</b> |
|
1924 </b><br> |
|
1925 <P> |
|
1926 The <b>pcre_dfa_exec()</b> function returns a negative number when it fails. |
|
1927 Many of the errors are the same as for <b>pcre_exec()</b>, and these are |
|
1928 described |
|
1929 <a href="#errorlist">above.</a> |
|
1930 There are in addition the following errors that are specific to |
|
1931 <b>pcre_dfa_exec()</b>: |
|
1932 <pre> |
|
1933 PCRE_ERROR_DFA_UITEM (-16) |
|
1934 </pre> |
|
1935 This return is given if <b>pcre_dfa_exec()</b> encounters an item in the pattern |
|
1936 that it does not support, for instance, the use of \C or a back reference. |
|
1937 <pre> |
|
1938 PCRE_ERROR_DFA_UCOND (-17) |
|
1939 </pre> |
|
1940 This return is given if <b>pcre_dfa_exec()</b> encounters a condition item that |
|
1941 uses a back reference for the condition, or a test for recursion in a specific |
|
1942 group. These are not supported. |
|
1943 <pre> |
|
1944 PCRE_ERROR_DFA_UMLIMIT (-18) |
|
1945 </pre> |
|
1946 This return is given if <b>pcre_dfa_exec()</b> is called with an <i>extra</i> |
|
1947 block that contains a setting of the <i>match_limit</i> field. This is not |
|
1948 supported (it is meaningless). |
|
1949 <pre> |
|
1950 PCRE_ERROR_DFA_WSSIZE (-19) |
|
1951 </pre> |
|
1952 This return is given if <b>pcre_dfa_exec()</b> runs out of space in the |
|
1953 <i>workspace</i> vector. |
|
1954 <pre> |
|
1955 PCRE_ERROR_DFA_RECURSE (-20) |
|
1956 </pre> |
|
1957 When a recursive subpattern is processed, the matching function calls itself |
|
1958 recursively, using private vectors for <i>ovector</i> and <i>workspace</i>. This |
|
1959 error is given if the output vector is not large enough. This should be |
|
1960 extremely rare, as a vector of size 1000 is used. |
|
1961 </P> |
|
1962 <br><a name="SEC20" href="#TOC1">SEE ALSO</a><br> |
|
1963 <P> |
|
1964 <b>pcrebuild</b>(3), <b>pcrecallout</b>(3), <b>pcrecpp(3)</b>(3), |
|
1965 <b>pcrematching</b>(3), <b>pcrepartial</b>(3), <b>pcreposix</b>(3), |
|
1966 <b>pcreprecompile</b>(3), <b>pcresample</b>(3), <b>pcrestack</b>(3). |
|
1967 </P> |
|
1968 <br><a name="SEC21" href="#TOC1">AUTHOR</a><br> |
|
1969 <P> |
|
1970 Philip Hazel |
|
1971 <br> |
|
1972 University Computing Service |
|
1973 <br> |
|
1974 Cambridge CB2 3QH, England. |
|
1975 <br> |
|
1976 </P> |
|
1977 <br><a name="SEC22" href="#TOC1">REVISION</a><br> |
|
1978 <P> |
|
1979 Last updated: 24 August 2008 |
|
1980 <br> |
|
1981 Copyright © 1997-2008 University of Cambridge. |
|
1982 <br> |
|
1983 <p> |
|
1984 Return to the <a href="index.html">PCRE index page</a>. |
|
1985 </p> |