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