« back to all changes in this revision
Viewing changes to doc/pcreapi.3
- browse files at revision 3
- compare with another revision
- download diff
- download tarball
- view history from revision 3
- Committer: Bazaar Package Importer
- Author(s): Andreas Metzler
- Date: 2004-03-12 13:23:02 UTC
- mfrom: (1.1.1 upstream)
- Revision ID: james.westby@ubuntu.com-20040312132302-id6ksx1l8dwssbw9
Tags: 4.5-1.1
* NMU to fix rc-bugs.
* Update libtool related files to fix build-error on mips, keep original
config.in, as it is no generated file. (Closes: #237265)
* pcregrep replaces pgrep. (Closes: #237564)
* Bump shlibs, pcre 4.5 includes two new functions.
* Let pgrep's /usr/share/doc symlink point to the package it depends on,
pcregrep.
* Update libtool related files to fix build-error on mips, keep original
config.in, as it is no generated file. (Closes: #237265)
* pcregrep replaces pgrep. (Closes: #237564)
* Bump shlibs, pcre 4.5 includes two new functions.
* Let pgrep's /usr/share/doc symlink point to the package it depends on,
pcregrep.
- files added:
- debian/README.Versioning.libtool
- doc/html
- files removed:
- Makefile
- files modified:
- AUTHORS
added
removed
doc/pcreapi.3
1
.TH PCRE 3
2
.SH NAME
3
PCRE - Perl-compatible regular expressions
4
.SH SYNOPSIS OF PCRE API
5
.rs
6
.sp
7
.B #include <pcre.h>
8
.PP
9
.SM
10
.br
11
.B pcre *pcre_compile(const char *\fIpattern\fR, int \fIoptions\fR,
12
.ti +5n
13
.B const char **\fIerrptr\fR, int *\fIerroffset\fR,
14
.ti +5n
15
.B const unsigned char *\fItableptr\fR);
16
.PP
17
.br
18
.B pcre_extra *pcre_study(const pcre *\fIcode\fR, int \fIoptions\fR,
19
.ti +5n
20
.B const char **\fIerrptr\fR);
21
.PP
22
.br
23
.B int pcre_exec(const pcre *\fIcode\fR, "const pcre_extra *\fIextra\fR,"
24
.ti +5n
25
.B "const char *\fIsubject\fR," int \fIlength\fR, int \fIstartoffset\fR,
26
.ti +5n
27
.B int \fIoptions\fR, int *\fIovector\fR, int \fIovecsize\fR);
28
.PP
29
.br
30
.B int pcre_copy_named_substring(const pcre *\fIcode\fR,
31
.ti +5n
32
.B const char *\fIsubject\fR, int *\fIovector\fR,
33
.ti +5n
34
.B int \fIstringcount\fR, const char *\fIstringname\fR,
35
.ti +5n
36
.B char *\fIbuffer\fR, int \fIbuffersize\fR);
37
.PP
38
.br
39
.B int pcre_copy_substring(const char *\fIsubject\fR, int *\fIovector\fR,
40
.ti +5n
41
.B int \fIstringcount\fR, int \fIstringnumber\fR, char *\fIbuffer\fR,
42
.ti +5n
43
.B int \fIbuffersize\fR);
44
.PP
45
.br
46
.B int pcre_get_named_substring(const pcre *\fIcode\fR,
47
.ti +5n
48
.B const char *\fIsubject\fR, int *\fIovector\fR,
49
.ti +5n
50
.B int \fIstringcount\fR, const char *\fIstringname\fR,
51
.ti +5n
52
.B const char **\fIstringptr\fR);
53
.PP
54
.br
55
.B int pcre_get_stringnumber(const pcre *\fIcode\fR,
56
.ti +5n
57
.B const char *\fIname\fR);
58
.PP
59
.br
60
.B int pcre_get_substring(const char *\fIsubject\fR, int *\fIovector\fR,
61
.ti +5n
62
.B int \fIstringcount\fR, int \fIstringnumber\fR,
63
.ti +5n
64
.B const char **\fIstringptr\fR);
65
.PP
66
.br
67
.B int pcre_get_substring_list(const char *\fIsubject\fR,
68
.ti +5n
69
.B int *\fIovector\fR, int \fIstringcount\fR, "const char ***\fIlistptr\fR);"
70
.PP
71
.br
72
.B void pcre_free_substring(const char *\fIstringptr\fR);
73
.PP
74
.br
75
.B void pcre_free_substring_list(const char **\fIstringptr\fR);
76
.PP
77
.br
78
.B const unsigned char *pcre_maketables(void);
79
.PP
80
.br
81
.B int pcre_fullinfo(const pcre *\fIcode\fR, "const pcre_extra *\fIextra\fR,"
82
.ti +5n
83
.B int \fIwhat\fR, void *\fIwhere\fR);
84
.PP
85
.br
86
.B int pcre_info(const pcre *\fIcode\fR, int *\fIoptptr\fR, int
87
.B *\fIfirstcharptr\fR);
88
.PP
89
.br
90
.B int pcre_config(int \fIwhat\fR, void *\fIwhere\fR);
91
.PP
92
.br
93
.B char *pcre_version(void);
94
.PP
95
.br
96
.B void *(*pcre_malloc)(size_t);
97
.PP
98
.br
99
.B void (*pcre_free)(void *);
100
.PP
101
.br
102
.B void *(*pcre_stack_malloc)(size_t);
103
.PP
104
.br
105
.B void (*pcre_stack_free)(void *);
106
.PP
107
.br
108
.B int (*pcre_callout)(pcre_callout_block *);
109
110
.SH PCRE API
111
.rs
112
.sp
113
PCRE has its own native API, which is described in this document. There is also
114
a set of wrapper functions that correspond to the POSIX regular expression API.
115
These are described in the \fBpcreposix\fR documentation.
116
117
The native API function prototypes are defined in the header file \fBpcre.h\fR,
118
and on Unix systems the library itself is called \fBlibpcre.a\fR, so can be
119
accessed by adding \fB-lpcre\fR to the command for linking an application which
120
calls it. The header file defines the macros PCRE_MAJOR and PCRE_MINOR to
121
contain the major and minor release numbers for the library. Applications can
122
use these to include support for different releases.
123
124
The functions \fBpcre_compile()\fR, \fBpcre_study()\fR, and \fBpcre_exec()\fR
125
are used for compiling and matching regular expressions. A sample program that
126
demonstrates the simplest way of using them is given in the file
127
\fIpcredemo.c\fR. The \fBpcresample\fR documentation describes how to run it.
128
129
There are convenience functions for extracting captured substrings from a
130
matched subject string. They are:
131
132
\fBpcre_copy_substring()\fR
133
\fBpcre_copy_named_substring()\fR
134
\fBpcre_get_substring()\fR
135
\fBpcre_get_named_substring()\fR
136
\fBpcre_get_substring_list()\fR
137
138
\fBpcre_free_substring()\fR and \fBpcre_free_substring_list()\fR are also
139
provided, to free the memory used for extracted strings.
140
141
The function \fBpcre_maketables()\fR is used (optionally) to build a set of
142
character tables in the current locale for passing to \fBpcre_compile()\fR.
143
144
The function \fBpcre_fullinfo()\fR is used to find out information about a
145
compiled pattern; \fBpcre_info()\fR is an obsolete version which returns only
146
some of the available information, but is retained for backwards compatibility.
147
The function \fBpcre_version()\fR returns a pointer to a string containing the
148
version of PCRE and its date of release.
149
150
The global variables \fBpcre_malloc\fR and \fBpcre_free\fR initially contain
151
the entry points of the standard \fBmalloc()\fR and \fBfree()\fR functions
152
respectively. PCRE calls the memory management functions via these variables,
153
so a calling program can replace them if it wishes to intercept the calls. This
154
should be done before calling any PCRE functions.
155
156
The global variables \fBpcre_stack_malloc\fR and \fBpcre_stack_free\fR are also
157
indirections to memory management functions. These special functions are used
158
only when PCRE is compiled to use the heap for remembering data, instead of
159
recursive function calls. This is a non-standard way of building PCRE, for use
160
in environments that have limited stacks. Because of the greater use of memory
161
management, it runs more slowly. Separate functions are provided so that
162
special-purpose external code can be used for this case. When used, these
163
functions are always called in a stack-like manner (last obtained, first
164
freed), and always for memory blocks of the same size.
165
166
The global variable \fBpcre_callout\fR initially contains NULL. It can be set
167
by the caller to a "callout" function, which PCRE will then call at specified
168
points during a matching operation. Details are given in the \fBpcrecallout\fR
169
documentation.
170
171
.SH MULTITHREADING
172
.rs
173
.sp
174
The PCRE functions can be used in multi-threading applications, with the
175
proviso that the memory management functions pointed to by \fBpcre_malloc\fR,
176
\fBpcre_free\fR, \fBpcre_stack_malloc\fR, and \fBpcre_stack_free\fR, and the
177
callout function pointed to by \fBpcre_callout\fR, are shared by all threads.
178
179
The compiled form of a regular expression is not altered during matching, so
180
the same compiled pattern can safely be used by several threads at once.
181
182
.SH CHECKING BUILD-TIME OPTIONS
183
.rs
184
.sp
185
.B int pcre_config(int \fIwhat\fR, void *\fIwhere\fR);
186
.PP
187
The function \fBpcre_config()\fR makes it possible for a PCRE client to
188
discover which optional features have been compiled into the PCRE library. The
189
.\" HREF
190
\fBpcrebuild\fR
191
.\"
192
documentation has more details about these optional features.
193
194
The first argument for \fBpcre_config()\fR is an integer, specifying which
195
information is required; the second argument is a pointer to a variable into
196
which the information is placed. The following information is available:
197
198
PCRE_CONFIG_UTF8
199
200
The output is an integer that is set to one if UTF-8 support is available;
201
otherwise it is set to zero.
202
203
PCRE_CONFIG_NEWLINE
204
205
The output is an integer that is set to the value of the code that is used for
206
the newline character. It is either linefeed (10) or carriage return (13), and
207
should normally be the standard character for your operating system.
208
209
PCRE_CONFIG_LINK_SIZE
210
211
The output is an integer that contains the number of bytes used for internal
212
linkage in compiled regular expressions. The value is 2, 3, or 4. Larger values
213
allow larger regular expressions to be compiled, at the expense of slower
214
matching. The default value of 2 is sufficient for all but the most massive
215
patterns, since it allows the compiled pattern to be up to 64K in size.
216
217
PCRE_CONFIG_POSIX_MALLOC_THRESHOLD
218
219
The output is an integer that contains the threshold above which the POSIX
220
interface uses \fBmalloc()\fR for output vectors. Further details are given in
221
the \fBpcreposix\fR documentation.
222
223
PCRE_CONFIG_MATCH_LIMIT
224
225
The output is an integer that gives the default limit for the number of
226
internal matching function calls in a \fBpcre_exec()\fR execution. Further
227
details are given with \fBpcre_exec()\fR below.
228
229
PCRE_CONFIG_STACKRECURSE
230
231
The output is an integer that is set to one if internal recursion is
232
implemented by recursive function calls that use the stack to remember their
233
state. This is the usual way that PCRE is compiled. The output is zero if PCRE
234
was compiled to use blocks of data on the heap instead of recursive function
235
calls. In this case, \fBpcre_stack_malloc\fR and \fBpcre_stack_free\fR are
236
called to manage memory blocks on the heap, thus avoiding the use of the stack.
237
238
.SH COMPILING A PATTERN
239
.rs
240
.sp
241
.B pcre *pcre_compile(const char *\fIpattern\fR, int \fIoptions\fR,
242
.ti +5n
243
.B const char **\fIerrptr\fR, int *\fIerroffset\fR,
244
.ti +5n
245
.B const unsigned char *\fItableptr\fR);
246
.PP
247
248
The function \fBpcre_compile()\fR is called to compile a pattern into an
249
internal form. The pattern is a C string terminated by a binary zero, and
250
is passed in the argument \fIpattern\fR. A pointer to a single block of memory
251
that is obtained via \fBpcre_malloc\fR is returned. This contains the compiled
252
code and related data. The \fBpcre\fR type is defined for the returned block;
253
this is a typedef for a structure whose contents are not externally defined. It
254
is up to the caller to free the memory when it is no longer required.
255
256
Although the compiled code of a PCRE regex is relocatable, that is, it does not
257
depend on memory location, the complete \fBpcre\fR data block is not
258
fully relocatable, because it contains a copy of the \fItableptr\fR argument,
259
which is an address (see below).
260
261
The \fIoptions\fR argument contains independent bits that affect the
262
compilation. It should be zero if no options are required. Some of the options,
263
in particular, those that are compatible with Perl, can also be set and unset
264
from within the pattern (see the detailed description of regular expressions
265
in the \fBpcrepattern\fR documentation). For these options, the contents of the
266
\fIoptions\fR argument specifies their initial settings at the start of
267
compilation and execution. The PCRE_ANCHORED option can be set at the time of
268
matching as well as at compile time.
269
270
If \fIerrptr\fR is NULL, \fBpcre_compile()\fR returns NULL immediately.
271
Otherwise, if compilation of a pattern fails, \fBpcre_compile()\fR returns
272
NULL, and sets the variable pointed to by \fIerrptr\fR to point to a textual
273
error message. The offset from the start of the pattern to the character where
274
the error was discovered is placed in the variable pointed to by
275
\fIerroffset\fR, which must not be NULL. If it is, an immediate error is given.
276
277
If the final argument, \fItableptr\fR, is NULL, PCRE uses a default set of
278
character tables which are built when it is compiled, using the default C
279
locale. Otherwise, \fItableptr\fR must be the result of a call to
280
\fBpcre_maketables()\fR. See the section on locale support below.
281
282
This code fragment shows a typical straightforward call to \fBpcre_compile()\fR:
283
284
pcre *re;
285
const char *error;
286
int erroffset;
287
re = pcre_compile(
288
"^A.*Z", /* the pattern */
289
0, /* default options */
290
&error, /* for error message */
291
&erroffset, /* for error offset */
292
NULL); /* use default character tables */
293
294
The following option bits are defined:
295
296
PCRE_ANCHORED
297
298
If this bit is set, the pattern is forced to be "anchored", that is, it is
299
constrained to match only at the first matching point in the string which is
300
being searched (the "subject string"). This effect can also be achieved by
301
appropriate constructs in the pattern itself, which is the only way to do it in
302
Perl.
303
304
PCRE_CASELESS
305
306
If this bit is set, letters in the pattern match both upper and lower case
307
letters. It is equivalent to Perl's /i option, and it can be changed within a
308
pattern by a (?i) option setting.
309
310
PCRE_DOLLAR_ENDONLY
311
312
If this bit is set, a dollar metacharacter in the pattern matches only at the
313
end of the subject string. Without this option, a dollar also matches
314
immediately before the final character if it is a newline (but not before any
315
other newlines). The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is
316
set. There is no equivalent to this option in Perl, and no way to set it within
317
a pattern.
318
319
PCRE_DOTALL
320
321
If this bit is set, a dot metacharater in the pattern matches all characters,
322
including newlines. Without it, newlines are excluded. This option is
323
equivalent to Perl's /s option, and it can be changed within a pattern by a
324
(?s) option setting. A negative class such as [^a] always matches a newline
325
character, independent of the setting of this option.
326
327
PCRE_EXTENDED
328
329
If this bit is set, whitespace data characters in the pattern are totally
330
ignored except when escaped or inside a character class. Whitespace does not
331
include the VT character (code 11). In addition, characters between an
332
unescaped # outside a character class and the next newline character,
333
inclusive, are also ignored. This is equivalent to Perl's /x option, and it can
334
be changed within a pattern by a (?x) option setting.
335
336
This option makes it possible to include comments inside complicated patterns.
337
Note, however, that this applies only to data characters. Whitespace characters
338
may never appear within special character sequences in a pattern, for example
339
within the sequence (?( which introduces a conditional subpattern.
340
341
PCRE_EXTRA
342
343
This option was invented in order to turn on additional functionality of PCRE
344
that is incompatible with Perl, but it is currently of very little use. When
345
set, any backslash in a pattern that is followed by a letter that has no
346
special meaning causes an error, thus reserving these combinations for future
347
expansion. By default, as in Perl, a backslash followed by a letter with no
348
special meaning is treated as a literal. There are at present no other features
349
controlled by this option. It can also be set by a (?X) option setting within a
350
pattern.
351
352
PCRE_MULTILINE
353
354
By default, PCRE treats the subject string as consisting of a single "line" of
355
characters (even if it actually contains several newlines). The "start of line"
356
metacharacter (^) matches only at the start of the string, while the "end of
357
line" metacharacter ($) matches only at the end of the string, or before a
358
terminating newline (unless PCRE_DOLLAR_ENDONLY is set). This is the same as
359
Perl.
360
361
When PCRE_MULTILINE it is set, the "start of line" and "end of line" constructs
362
match immediately following or immediately before any newline in the subject
363
string, respectively, as well as at the very start and end. This is equivalent
364
to Perl's /m option, and it can be changed within a pattern by a (?m) option
365
setting. If there are no "\\n" characters in a subject string, or no
366
occurrences of ^ or $ in a pattern, setting PCRE_MULTILINE has no effect.
367
368
PCRE_NO_AUTO_CAPTURE
369
370
If this option is set, it disables the use of numbered capturing parentheses in
371
the pattern. Any opening parenthesis that is not followed by ? behaves as if it
372
were followed by ?: but named parentheses can still be used for capturing (and
373
they acquire numbers in the usual way). There is no equivalent of this option
374
in Perl.
375
376
PCRE_UNGREEDY
377
378
This option inverts the "greediness" of the quantifiers so that they are not
379
greedy by default, but become greedy if followed by "?". It is not compatible
380
with Perl. It can also be set by a (?U) option setting within the pattern.
381
382
PCRE_UTF8
383
384
This option causes PCRE to regard both the pattern and the subject as strings
385
of UTF-8 characters instead of single-byte character strings. However, it is
386
available only if PCRE has been built to include UTF-8 support. If not, the use
387
of this option provokes an error. Details of how this option changes the
388
behaviour of PCRE are given in the
389
.\" HTML <a href="pcre.html#utf8support">
390
.\" </a>
391
section on UTF-8 support
392
.\"
393
in the main
394
.\" HREF
395
\fBpcre\fR
396
.\"
397
page.
398
399
PCRE_NO_UTF8_CHECK
400
401
When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string is
402
automatically checked. If an invalid UTF-8 sequence of bytes is found,
403
\fBpcre_compile()\fR returns an error. If you already know that your pattern is
404
valid, and you want to skip this check for performance reasons, you can set the
405
PCRE_NO_UTF8_CHECK option. When it is set, the effect of passing an invalid
406
UTF-8 string as a pattern is undefined. It may cause your program to crash.
407
Note that there is a similar option for suppressing the checking of subject
408
strings passed to \fBpcre_exec()\fR.
409
410
411
.SH STUDYING A PATTERN
412
.rs
413
.sp
414
.B pcre_extra *pcre_study(const pcre *\fIcode\fR, int \fIoptions\fR,
415
.ti +5n
416
.B const char **\fIerrptr\fR);
417
.PP
418
When a pattern is going to be used several times, it is worth spending more
419
time analyzing it in order to speed up the time taken for matching. The
420
function \fBpcre_study()\fR takes a pointer to a compiled pattern as its first
421
argument. If studing the pattern produces additional information that will help
422
speed up matching, \fBpcre_study()\fR returns a pointer to a \fBpcre_extra\fR
423
block, in which the \fIstudy_data\fR field points to the results of the study.
424
425
The returned value from a \fBpcre_study()\fR can be passed directly to
426
\fBpcre_exec()\fR. However, the \fBpcre_extra\fR block also contains other
427
fields that can be set by the caller before the block is passed; these are
428
described below. If studying the pattern does not produce any additional
429
information, \fBpcre_study()\fR returns NULL. In that circumstance, if the
430
calling program wants to pass some of the other fields to \fBpcre_exec()\fR, it
431
must set up its own \fBpcre_extra\fR block.
432
433
The second argument contains option bits. At present, no options are defined
434
for \fBpcre_study()\fR, and this argument should always be zero.
435
436
The third argument for \fBpcre_study()\fR is a pointer for an error message. If
437
studying succeeds (even if no data is returned), the variable it points to is
438
set to NULL. Otherwise it points to a textual error message. You should
439
therefore test the error pointer for NULL after calling \fBpcre_study()\fR, to
440
be sure that it has run successfully.
441
442
This is a typical call to \fBpcre_study\fR():
443
444
pcre_extra *pe;
445
pe = pcre_study(
446
re, /* result of pcre_compile() */
447
0, /* no options exist */
448
&error); /* set to NULL or points to a message */
449
450
At present, studying a pattern is useful only for non-anchored patterns that do
451
not have a single fixed starting character. A bitmap of possible starting
452
characters is created.
453
454
.\" HTML <a name="localesupport"></a>
455
.SH LOCALE SUPPORT
456
.rs
457
.sp
458
PCRE handles caseless matching, and determines whether characters are letters,
459
digits, or whatever, by reference to a set of tables. When running in UTF-8
460
mode, this applies only to characters with codes less than 256. The library
461
contains a default set of tables that is created in the default C locale when
462
PCRE is compiled. This is used when the final argument of \fBpcre_compile()\fR
463
is NULL, and is sufficient for many applications.
464
465
An alternative set of tables can, however, be supplied. Such tables are built
466
by calling the \fBpcre_maketables()\fR function, which has no arguments, in the
467
relevant locale. The result can then be passed to \fBpcre_compile()\fR as often
468
as necessary. For example, to build and use tables that are appropriate for the
469
French locale (where accented characters with codes greater than 128 are
470
treated as letters), the following code could be used:
471
472
setlocale(LC_CTYPE, "fr");
473
tables = pcre_maketables();
474
re = pcre_compile(..., tables);
475
476
The tables are built in memory that is obtained via \fBpcre_malloc\fR. The
477
pointer that is passed to \fBpcre_compile\fR is saved with the compiled
478
pattern, and the same tables are used via this pointer by \fBpcre_study()\fR
479
and \fBpcre_exec()\fR. Thus, for any single pattern, compilation, studying and
480
matching all happen in the same locale, but different patterns can be compiled
481
in different locales. It is the caller's responsibility to ensure that the
482
memory containing the tables remains available for as long as it is needed.
483
484
.SH INFORMATION ABOUT A PATTERN
485
.rs
486
.sp
487
.B int pcre_fullinfo(const pcre *\fIcode\fR, "const pcre_extra *\fIextra\fR,"
488
.ti +5n
489
.B int \fIwhat\fR, void *\fIwhere\fR);
490
.PP
491
The \fBpcre_fullinfo()\fR function returns information about a compiled
492
pattern. It replaces the obsolete \fBpcre_info()\fR function, which is
493
nevertheless retained for backwards compability (and is documented below).
494
495
The first argument for \fBpcre_fullinfo()\fR is a pointer to the compiled
496
pattern. The second argument is the result of \fBpcre_study()\fR, or NULL if
497
the pattern was not studied. The third argument specifies which piece of
498
information is required, and the fourth argument is a pointer to a variable
499
to receive the data. The yield of the function is zero for success, or one of
500
the following negative numbers:
501
502
PCRE_ERROR_NULL the argument \fIcode\fR was NULL
503
the argument \fIwhere\fR was NULL
504
PCRE_ERROR_BADMAGIC the "magic number" was not found
505
PCRE_ERROR_BADOPTION the value of \fIwhat\fR was invalid
506
507
Here is a typical call of \fBpcre_fullinfo()\fR, to obtain the length of the
508
compiled pattern:
509
510
int rc;
511
unsigned long int length;
512
rc = pcre_fullinfo(
513
re, /* result of pcre_compile() */
514
pe, /* result of pcre_study(), or NULL */
515
PCRE_INFO_SIZE, /* what is required */
516
&length); /* where to put the data */
517
518
The possible values for the third argument are defined in \fBpcre.h\fR, and are
519
as follows:
520
521
PCRE_INFO_BACKREFMAX
522
523
Return the number of the highest back reference in the pattern. The fourth
524
argument should point to an \fBint\fR variable. Zero is returned if there are
525
no back references.
526
527
PCRE_INFO_CAPTURECOUNT
528
529
Return the number of capturing subpatterns in the pattern. The fourth argument
530
should point to an \fbint\fR variable.
531
532
PCRE_INFO_FIRSTBYTE
533
534
Return information about the first byte of any matched string, for a
535
non-anchored pattern. (This option used to be called PCRE_INFO_FIRSTCHAR; the
536
old name is still recognized for backwards compatibility.)
537
538
If there is a fixed first byte, e.g. from a pattern such as (cat|cow|coyote),
539
it is returned in the integer pointed to by \fIwhere\fR. Otherwise, if either
540
541
(a) the pattern was compiled with the PCRE_MULTILINE option, and every branch
542
starts with "^", or
543
544
(b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not set
545
(if it were set, the pattern would be anchored),
546
547
-1 is returned, indicating that the pattern matches only at the start of a
548
subject string or after any newline within the string. Otherwise -2 is
549
returned. For anchored patterns, -2 is returned.
550
551
PCRE_INFO_FIRSTTABLE
552
553
If the pattern was studied, and this resulted in the construction of a 256-bit
554
table indicating a fixed set of bytes for the first byte in any matching
555
string, a pointer to the table is returned. Otherwise NULL is returned. The
556
fourth argument should point to an \fBunsigned char *\fR variable.
557
558
PCRE_INFO_LASTLITERAL
559
560
Return the value of the rightmost literal byte that must exist in any matched
561
string, other than at its start, if such a byte has been recorded. The fourth
562
argument should point to an \fBint\fR variable. If there is no such byte, -1 is
563
returned. For anchored patterns, a last literal byte is recorded only if it
564
follows something of variable length. For example, for the pattern
565
/^a\\d+z\\d+/ the returned value is "z", but for /^a\\dz\\d/ the returned value
566
is -1.
567
568
PCRE_INFO_NAMECOUNT
569
PCRE_INFO_NAMEENTRYSIZE
570
PCRE_INFO_NAMETABLE
571
572
PCRE supports the use of named as well as numbered capturing parentheses. The
573
names are just an additional way of identifying the parentheses, which still
574
acquire a number. A caller that wants to extract data from a named subpattern
575
must convert the name to a number in order to access the correct pointers in
576
the output vector (described with \fBpcre_exec()\fR below). In order to do
577
this, it must first use these three values to obtain the name-to-number mapping
578
table for the pattern.
579
580
The map consists of a number of fixed-size entries. PCRE_INFO_NAMECOUNT gives
581
the number of entries, and PCRE_INFO_NAMEENTRYSIZE gives the size of each
582
entry; both of these return an \fBint\fR value. The entry size depends on the
583
length of the longest name. PCRE_INFO_NAMETABLE returns a pointer to the first
584
entry of the table (a pointer to \fBchar\fR). The first two bytes of each entry
585
are the number of the capturing parenthesis, most significant byte first. The
586
rest of the entry is the corresponding name, zero terminated. The names are in
587
alphabetical order. For example, consider the following pattern (assume
588
PCRE_EXTENDED is set, so white space - including newlines - is ignored):
589
590
(?P<date> (?P<year>(\\d\\d)?\\d\\d) -
591
(?P<month>\\d\\d) - (?P<day>\\d\\d) )
592
593
There are four named subpatterns, so the table has four entries, and each entry
594
in the table is eight bytes long. The table is as follows, with non-printing
595
bytes shows in hex, and undefined bytes shown as ??:
596
597
00 01 d a t e 00 ??
598
00 05 d a y 00 ?? ??
599
00 04 m o n t h 00
600
00 02 y e a r 00 ??
601
602
When writing code to extract data from named subpatterns, remember that the
603
length of each entry may be different for each compiled pattern.
604
605
PCRE_INFO_OPTIONS
606
607
Return a copy of the options with which the pattern was compiled. The fourth
608
argument should point to an \fBunsigned long int\fR variable. These option bits
609
are those specified in the call to \fBpcre_compile()\fR, modified by any
610
top-level option settings within the pattern itself.
611
612
A pattern is automatically anchored by PCRE if all of its top-level
613
alternatives begin with one of the following:
614
615
^ unless PCRE_MULTILINE is set
616
\\A always
617
\\G always
618
.* if PCRE_DOTALL is set and there are no back
619
references to the subpattern in which .* appears
620
621
For such patterns, the PCRE_ANCHORED bit is set in the options returned by
622
\fBpcre_fullinfo()\fR.
623
624
PCRE_INFO_SIZE
625
626
Return the size of the compiled pattern, that is, the value that was passed as
627
the argument to \fBpcre_malloc()\fR when PCRE was getting memory in which to
628
place the compiled data. The fourth argument should point to a \fBsize_t\fR
629
variable.
630
631
PCRE_INFO_STUDYSIZE
632
633
Returns the size of the data block pointed to by the \fIstudy_data\fR field in
634
a \fBpcre_extra\fR block. That is, it is the value that was passed to
635
\fBpcre_malloc()\fR when PCRE was getting memory into which to place the data
636
created by \fBpcre_study()\fR. The fourth argument should point to a
637
\fBsize_t\fR variable.
638
639
.SH OBSOLETE INFO FUNCTION
640
.rs
641
.sp
642
.B int pcre_info(const pcre *\fIcode\fR, int *\fIoptptr\fR, int
643
.B *\fIfirstcharptr\fR);
644
.PP
645
The \fBpcre_info()\fR function is now obsolete because its interface is too
646
restrictive to return all the available data about a compiled pattern. New
647
programs should use \fBpcre_fullinfo()\fR instead. The yield of
648
\fBpcre_info()\fR is the number of capturing subpatterns, or one of the
649
following negative numbers:
650
651
PCRE_ERROR_NULL the argument \fIcode\fR was NULL
652
PCRE_ERROR_BADMAGIC the "magic number" was not found
653
654
If the \fIoptptr\fR argument is not NULL, a copy of the options with which the
655
pattern was compiled is placed in the integer it points to (see
656
PCRE_INFO_OPTIONS above).
657
658
If the pattern is not anchored and the \fIfirstcharptr\fR argument is not NULL,
659
it is used to pass back information about the first character of any matched
660
string (see PCRE_INFO_FIRSTBYTE above).
661
662
.SH MATCHING A PATTERN
663
.rs
664
.sp
665
.B int pcre_exec(const pcre *\fIcode\fR, "const pcre_extra *\fIextra\fR,"
666
.ti +5n
667
.B "const char *\fIsubject\fR," int \fIlength\fR, int \fIstartoffset\fR,
668
.ti +5n
669
.B int \fIoptions\fR, int *\fIovector\fR, int \fIovecsize\fR);
670
.PP
671
The function \fBpcre_exec()\fR is called to match a subject string against a
672
pre-compiled pattern, which is passed in the \fIcode\fR argument. If the
673
pattern has been studied, the result of the study should be passed in the
674
\fIextra\fR argument.
675
676
Here is an example of a simple call to \fBpcre_exec()\fR:
677
678
int rc;
679
int ovector[30];
680
rc = pcre_exec(
681
re, /* result of pcre_compile() */
682
NULL, /* we didn't study the pattern */
683
"some string", /* the subject string */
684
11, /* the length of the subject string */
685
0, /* start at offset 0 in the subject */
686
0, /* default options */
687
ovector, /* vector for substring information */
688
30); /* number of elements in the vector */
689
690
If the \fIextra\fR argument is not NULL, it must point to a \fBpcre_extra\fR
691
data block. The \fBpcre_study()\fR function returns such a block (when it
692
doesn't return NULL), but you can also create one for yourself, and pass
693
additional information in it. The fields in the block are as follows:
694
695
unsigned long int \fIflags\fR;
696
void *\fIstudy_data\fR;
697
unsigned long int \fImatch_limit\fR;
698
void *\fIcallout_data\fR;
699
700
The \fIflags\fR field is a bitmap that specifies which of the other fields
701
are set. The flag bits are:
702
703
PCRE_EXTRA_STUDY_DATA
704
PCRE_EXTRA_MATCH_LIMIT
705
PCRE_EXTRA_CALLOUT_DATA
706
707
Other flag bits should be set to zero. The \fIstudy_data\fR field is set in the
708
\fBpcre_extra\fR block that is returned by \fBpcre_study()\fR, together with
709
the appropriate flag bit. You should not set this yourself, but you can add to
710
the block by setting the other fields.
711
712
The \fImatch_limit\fR field provides a means of preventing PCRE from using up a
713
vast amount of resources when running patterns that are not going to match,
714
but which have a very large number of possibilities in their search trees. The
715
classic example is the use of nested unlimited repeats. Internally, PCRE uses a
716
function called \fBmatch()\fR which it calls repeatedly (sometimes
717
recursively). The limit is imposed on the number of times this function is
718
called during a match, which has the effect of limiting the amount of recursion
719
and backtracking that can take place. For patterns that are not anchored, the
720
count starts from zero for each position in the subject string.
721
722
The default limit for the library can be set when PCRE is built; the default
723
default is 10 million, which handles all but the most extreme cases. You can
724
reduce the default by suppling \fBpcre_exec()\fR with a \fRpcre_extra\fR block
725
in which \fImatch_limit\fR is set to a smaller value, and
726
PCRE_EXTRA_MATCH_LIMIT is set in the \fIflags\fR field. If the limit is
727
exceeded, \fBpcre_exec()\fR returns PCRE_ERROR_MATCHLIMIT.
728
729
The \fIpcre_callout\fR field is used in conjunction with the "callout" feature,
730
which is described in the \fBpcrecallout\fR documentation.
731
732
The PCRE_ANCHORED option can be passed in the \fIoptions\fR argument, whose
733
unused bits must be zero. This limits \fBpcre_exec()\fR to matching at the
734
first matching position. However, if a pattern was compiled with PCRE_ANCHORED,
735
or turned out to be anchored by virtue of its contents, it cannot be made
736
unachored at matching time.
737
738
When PCRE_UTF8 was set at compile time, the validity of the subject as a UTF-8
739
string is automatically checked, and the value of \fIstartoffset\fR is also
740
checked to ensure that it points to the start of a UTF-8 character. If an
741
invalid UTF-8 sequence of bytes is found, \fBpcre_exec()\fR returns the error
742
PCRE_ERROR_BADUTF8. If \fIstartoffset\fR contains an invalid value,
743
PCRE_ERROR_BADUTF8_OFFSET is returned.
744
745
If you already know that your subject is valid, and you want to skip these
746
checks for performance reasons, you can set the PCRE_NO_UTF8_CHECK option when
747
calling \fBpcre_exec()\fR. You might want to do this for the second and
748
subsequent calls to \fBpcre_exec()\fR if you are making repeated calls to find
749
all the matches in a single subject string. However, you should be sure that
750
the value of \fIstartoffset\fR points to the start of a UTF-8 character. When
751
PCRE_NO_UTF8_CHECK is set, the effect of passing an invalid UTF-8 string as a
752
subject, or a value of \fIstartoffset\fR that does not point to the start of a
753
UTF-8 character, is undefined. Your program may crash.
754
755
There are also three further options that can be set only at matching time:
756
757
PCRE_NOTBOL
758
759
The first character of the string is not the beginning of a line, so the
760
circumflex metacharacter should not match before it. Setting this without
761
PCRE_MULTILINE (at compile time) causes circumflex never to match.
762
763
PCRE_NOTEOL
764
765
The end of the string is not the end of a line, so the dollar metacharacter
766
should not match it nor (except in multiline mode) a newline immediately before
767
it. Setting this without PCRE_MULTILINE (at compile time) causes dollar never
768
to match.
769
770
PCRE_NOTEMPTY
771
772
An empty string is not considered to be a valid match if this option is set. If
773
there are alternatives in the pattern, they are tried. If all the alternatives
774
match the empty string, the entire match fails. For example, if the pattern
775
776
a?b?
777
778
is applied to a string not beginning with "a" or "b", it matches the empty
779
string at the start of the subject. With PCRE_NOTEMPTY set, this match is not
780
valid, so PCRE searches further into the string for occurrences of "a" or "b".
781
782
Perl has no direct equivalent of PCRE_NOTEMPTY, but it does make a special case
783
of a pattern match of the empty string within its \fBsplit()\fR function, and
784
when using the /g modifier. It is possible to emulate Perl's behaviour after
785
matching a null string by first trying the match again at the same offset with
786
PCRE_NOTEMPTY set, and then if that fails by advancing the starting offset (see
787
below) and trying an ordinary match again.
788
789
The subject string is passed to \fBpcre_exec()\fR as a pointer in
790
\fIsubject\fR, a length in \fIlength\fR, and a starting byte offset in
791
\fIstartoffset\fR. Unlike the pattern string, the subject may contain binary
792
zero bytes. When the starting offset is zero, the search for a match starts at
793
the beginning of the subject, and this is by far the most common case.
794
795
If the pattern was compiled with the PCRE_UTF8 option, the subject must be a
796
sequence of bytes that is a valid UTF-8 string, and the starting offset must
797
point to the beginning of a UTF-8 character. If an invalid UTF-8 string or
798
offset is passed, an error (either PCRE_ERROR_BADUTF8 or
799
PCRE_ERROR_BADUTF8_OFFSET) is returned, unless the option PCRE_NO_UTF8_CHECK is
800
set, in which case PCRE's behaviour is not defined.
801
802
A non-zero starting offset is useful when searching for another match in the
803
same subject by calling \fBpcre_exec()\fR again after a previous success.
804
Setting \fIstartoffset\fR differs from just passing over a shortened string and
805
setting PCRE_NOTBOL in the case of a pattern that begins with any kind of
806
lookbehind. For example, consider the pattern
807
808
\\Biss\\B
809
810
which finds occurrences of "iss" in the middle of words. (\\B matches only if
811
the current position in the subject is not a word boundary.) When applied to
812
the string "Mississipi" the first call to \fBpcre_exec()\fR finds the first
813
occurrence. If \fBpcre_exec()\fR is called again with just the remainder of the
814
subject, namely "issipi", it does not match, because \\B is always false at the
815
start of the subject, which is deemed to be a word boundary. However, if
816
\fBpcre_exec()\fR is passed the entire string again, but with \fIstartoffset\fR
817
set to 4, it finds the second occurrence of "iss" because it is able to look
818
behind the starting point to discover that it is preceded by a letter.
819
820
If a non-zero starting offset is passed when the pattern is anchored, one
821
attempt to match at the given offset is tried. This can only succeed if the
822
pattern does not require the match to be at the start of the subject.
823
824
In general, a pattern matches a certain portion of the subject, and in
825
addition, further substrings from the subject may be picked out by parts of the
826
pattern. Following the usage in Jeffrey Friedl's book, this is called
827
"capturing" in what follows, and the phrase "capturing subpattern" is used for
828
a fragment of a pattern that picks out a substring. PCRE supports several other
829
kinds of parenthesized subpattern that do not cause substrings to be captured.
830
831
Captured substrings are returned to the caller via a vector of integer offsets
832
whose address is passed in \fIovector\fR. The number of elements in the vector
833
is passed in \fIovecsize\fR. The first two-thirds of the vector is used to pass
834
back captured substrings, each substring using a pair of integers. The
835
remaining third of the vector is used as workspace by \fBpcre_exec()\fR while
836
matching capturing subpatterns, and is not available for passing back
837
information. The length passed in \fIovecsize\fR should always be a multiple of
838
three. If it is not, it is rounded down.
839
840
When a match has been successful, information about captured substrings is
841
returned in pairs of integers, starting at the beginning of \fIovector\fR, and
842
continuing up to two-thirds of its length at the most. The first element of a
843
pair is set to the offset of the first character in a substring, and the second
844
is set to the offset of the first character after the end of a substring. The
845
first pair, \fIovector[0]\fR and \fIovector[1]\fR, identify the portion of the
846
subject string matched by the entire pattern. The next pair is used for the
847
first capturing subpattern, and so on. The value returned by \fBpcre_exec()\fR
848
is the number of pairs that have been set. If there are no capturing
849
subpatterns, the return value from a successful match is 1, indicating that
850
just the first pair of offsets has been set.
851
852
Some convenience functions are provided for extracting the captured substrings
853
as separate strings. These are described in the following section.
854
855
It is possible for an capturing subpattern number \fIn+1\fR to match some
856
part of the subject when subpattern \fIn\fR has not been used at all. For
857
example, if the string "abc" is matched against the pattern (a|(z))(bc)
858
subpatterns 1 and 3 are matched, but 2 is not. When this happens, both offset
859
values corresponding to the unused subpattern are set to -1.
860
861
If a capturing subpattern is matched repeatedly, it is the last portion of the
862
string that it matched that gets returned.
863
864
If the vector is too small to hold all the captured substrings, it is used as
865
far as possible (up to two-thirds of its length), and the function returns a
866
value of zero. In particular, if the substring offsets are not of interest,
867
\fBpcre_exec()\fR may be called with \fIovector\fR passed as NULL and
868
\fIovecsize\fR as zero. However, if the pattern contains back references and
869
the \fIovector\fR isn't big enough to remember the related substrings, PCRE has
870
to get additional memory for use during matching. Thus it is usually advisable
871
to supply an \fIovector\fR.
872
873
Note that \fBpcre_info()\fR can be used to find out how many capturing
874
subpatterns there are in a compiled pattern. The smallest size for
875
\fIovector\fR that will allow for \fIn\fR captured substrings, in addition to
876
the offsets of the substring matched by the whole pattern, is (\fIn\fR+1)*3.
877
878
If \fBpcre_exec()\fR fails, it returns a negative number. The following are
879
defined in the header file:
880
881
PCRE_ERROR_NOMATCH (-1)
882
883
The subject string did not match the pattern.
884
885
PCRE_ERROR_NULL (-2)
886
887
Either \fIcode\fR or \fIsubject\fR was passed as NULL, or \fIovector\fR was
888
NULL and \fIovecsize\fR was not zero.
889
890
PCRE_ERROR_BADOPTION (-3)
891
892
An unrecognized bit was set in the \fIoptions\fR argument.
893
894
PCRE_ERROR_BADMAGIC (-4)
895
896
PCRE stores a 4-byte "magic number" at the start of the compiled code, to catch
897
the case when it is passed a junk pointer. This is the error it gives when the
898
magic number isn't present.
899
900
PCRE_ERROR_UNKNOWN_NODE (-5)
901
902
While running the pattern match, an unknown item was encountered in the
903
compiled pattern. This error could be caused by a bug in PCRE or by overwriting
904
of the compiled pattern.
905
906
PCRE_ERROR_NOMEMORY (-6)
907
908
If a pattern contains back references, but the \fIovector\fR that is passed to
909
\fBpcre_exec()\fR is not big enough to remember the referenced substrings, PCRE
910
gets a block of memory at the start of matching to use for this purpose. If the
911
call via \fBpcre_malloc()\fR fails, this error is given. The memory is freed at
912
the end of matching.
913
914
PCRE_ERROR_NOSUBSTRING (-7)
915
916
This error is used by the \fBpcre_copy_substring()\fR,
917
\fBpcre_get_substring()\fR, and \fBpcre_get_substring_list()\fR functions (see
918
below). It is never returned by \fBpcre_exec()\fR.
919
920
PCRE_ERROR_MATCHLIMIT (-8)
921
922
The recursion and backtracking limit, as specified by the \fImatch_limit\fR
923
field in a \fBpcre_extra\fR structure (or defaulted) was reached. See the
924
description above.
925
926
PCRE_ERROR_CALLOUT (-9)
927
928
This error is never generated by \fBpcre_exec()\fR itself. It is provided for
929
use by callout functions that want to yield a distinctive error code. See the
930
\fBpcrecallout\fR documentation for details.
931
932
PCRE_ERROR_BADUTF8 (-10)
933
934
A string that contains an invalid UTF-8 byte sequence was passed as a subject.
935
936
PCRE_ERROR_BADUTF8_OFFSET (-11)
937
938
The UTF-8 byte sequence that was passed as a subject was valid, but the value
939
of \fIstartoffset\fR did not point to the beginning of a UTF-8 character.
940
941
.SH EXTRACTING CAPTURED SUBSTRINGS BY NUMBER
942
.rs
943
.sp
944
.B int pcre_copy_substring(const char *\fIsubject\fR, int *\fIovector\fR,
945
.ti +5n
946
.B int \fIstringcount\fR, int \fIstringnumber\fR, char *\fIbuffer\fR,
947
.ti +5n
948
.B int \fIbuffersize\fR);
949
.PP
950
.br
951
.B int pcre_get_substring(const char *\fIsubject\fR, int *\fIovector\fR,
952
.ti +5n
953
.B int \fIstringcount\fR, int \fIstringnumber\fR,
954
.ti +5n
955
.B const char **\fIstringptr\fR);
956
.PP
957
.br
958
.B int pcre_get_substring_list(const char *\fIsubject\fR,
959
.ti +5n
960
.B int *\fIovector\fR, int \fIstringcount\fR, "const char ***\fIlistptr\fR);"
961
.PP
962
Captured substrings can be accessed directly by using the offsets returned by
963
\fBpcre_exec()\fR in \fIovector\fR. For convenience, the functions
964
\fBpcre_copy_substring()\fR, \fBpcre_get_substring()\fR, and
965
\fBpcre_get_substring_list()\fR are provided for extracting captured substrings
966
as new, separate, zero-terminated strings. These functions identify substrings
967
by number. The next section describes functions for extracting named
968
substrings. A substring that contains a binary zero is correctly extracted and
969
has a further zero added on the end, but the result is not, of course,
970
a C string.
971
972
The first three arguments are the same for all three of these functions:
973
\fIsubject\fR is the subject string which has just been successfully matched,
974
\fIovector\fR is a pointer to the vector of integer offsets that was passed to
975
\fBpcre_exec()\fR, and \fIstringcount\fR is the number of substrings that were
976
captured by the match, including the substring that matched the entire regular
977
expression. This is the value returned by \fBpcre_exec\fR if it is greater than
978
zero. If \fBpcre_exec()\fR returned zero, indicating that it ran out of space
979
in \fIovector\fR, the value passed as \fIstringcount\fR should be the size of
980
the vector divided by three.
981
982
The functions \fBpcre_copy_substring()\fR and \fBpcre_get_substring()\fR
983
extract a single substring, whose number is given as \fIstringnumber\fR. A
984
value of zero extracts the substring that matched the entire pattern, while
985
higher values extract the captured substrings. For \fBpcre_copy_substring()\fR,
986
the string is placed in \fIbuffer\fR, whose length is given by
987
\fIbuffersize\fR, while for \fBpcre_get_substring()\fR a new block of memory is
988
obtained via \fBpcre_malloc\fR, and its address is returned via
989
\fIstringptr\fR. The yield of the function is the length of the string, not
990
including the terminating zero, or one of
991
992
PCRE_ERROR_NOMEMORY (-6)
993
994
The buffer was too small for \fBpcre_copy_substring()\fR, or the attempt to get
995
memory failed for \fBpcre_get_substring()\fR.
996
997
PCRE_ERROR_NOSUBSTRING (-7)
998
999
There is no substring whose number is \fIstringnumber\fR.
1000
1001
The \fBpcre_get_substring_list()\fR function extracts all available substrings
1002
and builds a list of pointers to them. All this is done in a single block of
1003
memory which is obtained via \fBpcre_malloc\fR. The address of the memory block
1004
is returned via \fIlistptr\fR, which is also the start of the list of string
1005
pointers. The end of the list is marked by a NULL pointer. The yield of the
1006
function is zero if all went well, or
1007
1008
PCRE_ERROR_NOMEMORY (-6)
1009
1010
if the attempt to get the memory block failed.
1011
1012
When any of these functions encounter a substring that is unset, which can
1013
happen when capturing subpattern number \fIn+1\fR matches some part of the
1014
subject, but subpattern \fIn\fR has not been used at all, they return an empty
1015
string. This can be distinguished from a genuine zero-length substring by
1016
inspecting the appropriate offset in \fIovector\fR, which is negative for unset
1017
substrings.
1018
1019
The two convenience functions \fBpcre_free_substring()\fR and
1020
\fBpcre_free_substring_list()\fR can be used to free the memory returned by
1021
a previous call of \fBpcre_get_substring()\fR or
1022
\fBpcre_get_substring_list()\fR, respectively. They do nothing more than call
1023
the function pointed to by \fBpcre_free\fR, which of course could be called
1024
directly from a C program. However, PCRE is used in some situations where it is
1025
linked via a special interface to another programming language which cannot use
1026
\fBpcre_free\fR directly; it is for these cases that the functions are
1027
provided.
1028
1029
.SH EXTRACTING CAPTURED SUBSTRINGS BY NAME
1030
.rs
1031
.sp
1032
.B int pcre_copy_named_substring(const pcre *\fIcode\fR,
1033
.ti +5n
1034
.B const char *\fIsubject\fR, int *\fIovector\fR,
1035
.ti +5n
1036
.B int \fIstringcount\fR, const char *\fIstringname\fR,
1037
.ti +5n
1038
.B char *\fIbuffer\fR, int \fIbuffersize\fR);
1039
.PP
1040
.br
1041
.B int pcre_get_stringnumber(const pcre *\fIcode\fR,
1042
.ti +5n
1043
.B const char *\fIname\fR);
1044
.PP
1045
.br
1046
.B int pcre_get_named_substring(const pcre *\fIcode\fR,
1047
.ti +5n
1048
.B const char *\fIsubject\fR, int *\fIovector\fR,
1049
.ti +5n
1050
.B int \fIstringcount\fR, const char *\fIstringname\fR,
1051
.ti +5n
1052
.B const char **\fIstringptr\fR);
1053
.PP
1054
To extract a substring by name, you first have to find associated number. This
1055
can be done by calling \fBpcre_get_stringnumber()\fR. The first argument is the
1056
compiled pattern, and the second is the name. For example, for this pattern
1057
1058
ab(?<xxx>\\d+)...
1059
1060
the number of the subpattern called "xxx" is 1. Given the number, you can then
1061
extract the substring directly, or use one of the functions described in the
1062
previous section. For convenience, there are also two functions that do the
1063
whole job.
1064
1065
Most of the arguments of \fIpcre_copy_named_substring()\fR and
1066
\fIpcre_get_named_substring()\fR are the same as those for the functions that
1067
extract by number, and so are not re-described here. There are just two
1068
differences.
1069
1070
First, instead of a substring number, a substring name is given. Second, there
1071
is an extra argument, given at the start, which is a pointer to the compiled
1072
pattern. This is needed in order to gain access to the name-to-number
1073
translation table.
1074
1075
These functions call \fBpcre_get_stringnumber()\fR, and if it succeeds, they
1076
then call \fIpcre_copy_substring()\fR or \fIpcre_get_substring()\fR, as
1077
appropriate.
1078
1079
.in 0
1080
Last updated: 09 December 2003
1081
.br
1082
Copyright (c) 1997-2003 University of Cambridge.
Loggerhead is a web-based interface for Breezy
Version: 2.0.1