1 |
.TH PCRE 3
|
2 |
.SH NAME
|
3 |
PCRE - Perl-compatible regular expressions.
|
4 |
.SH SYNOPSIS OF POSIX API
|
5 |
.B #include <pcreposix.h>
|
6 |
.PP
|
7 |
.SM
|
8 |
.br
|
9 |
.B int regcomp(regex_t *\fIpreg\fR, const char *\fIpattern\fR,
|
10 |
.ti +5n
|
11 |
.B int \fIcflags\fR);
|
12 |
.PP
|
13 |
.br
|
14 |
.B int regexec(regex_t *\fIpreg\fR, const char *\fIstring\fR,
|
15 |
.ti +5n
|
16 |
.B size_t \fInmatch\fR, regmatch_t \fIpmatch\fR[], int \fIeflags\fR);
|
17 |
.PP
|
18 |
.br
|
19 |
.B size_t regerror(int \fIerrcode\fR, const regex_t *\fIpreg\fR,
|
20 |
.ti +5n
|
21 |
.B char *\fIerrbuf\fR, size_t \fIerrbuf_size\fR);
|
22 |
.PP
|
23 |
.br
|
24 |
.B void regfree(regex_t *\fIpreg\fR);
|
25 |
|
26 |
.SH DESCRIPTION
|
27 |
.rs
|
28 |
.sp
|
29 |
This set of functions provides a POSIX-style API to the PCRE regular expression
|
30 |
package. See the
|
31 |
.\" HREF
|
32 |
\fBpcreapi\fR
|
33 |
.\"
|
34 |
documentation for a description of the native API, which contains additional
|
35 |
functionality.
|
36 |
|
37 |
The functions described here are just wrapper functions that ultimately call
|
38 |
the PCRE native API. Their prototypes are defined in the \fBpcreposix.h\fR
|
39 |
header file, and on Unix systems the library itself is called
|
40 |
\fBpcreposix.a\fR, so can be accessed by adding \fB-lpcreposix\fR to the
|
41 |
command for linking an application which uses them. Because the POSIX functions
|
42 |
call the native ones, it is also necessary to add \fR-lpcre\fR.
|
43 |
|
44 |
I have implemented only those option bits that can be reasonably mapped to PCRE
|
45 |
native options. In addition, the options REG_EXTENDED and REG_NOSUB are defined
|
46 |
with the value zero. They have no effect, but since programs that are written
|
47 |
to the POSIX interface often use them, this makes it easier to slot in PCRE as
|
48 |
a replacement library. Other POSIX options are not even defined.
|
49 |
|
50 |
When PCRE is called via these functions, it is only the API that is POSIX-like
|
51 |
in style. The syntax and semantics of the regular expressions themselves are
|
52 |
still those of Perl, subject to the setting of various PCRE options, as
|
53 |
described below. "POSIX-like in style" means that the API approximates to the
|
54 |
POSIX definition; it is not fully POSIX-compatible, and in multi-byte encoding
|
55 |
domains it is probably even less compatible.
|
56 |
|
57 |
The header for these functions is supplied as \fBpcreposix.h\fR to avoid any
|
58 |
potential clash with other POSIX libraries. It can, of course, be renamed or
|
59 |
aliased as \fBregex.h\fR, which is the "correct" name. It provides two
|
60 |
structure types, \fIregex_t\fR for compiled internal forms, and
|
61 |
\fIregmatch_t\fR for returning captured substrings. It also defines some
|
62 |
constants whose names start with "REG_"; these are used for setting options and
|
63 |
identifying error codes.
|
64 |
|
65 |
.SH COMPILING A PATTERN
|
66 |
.rs
|
67 |
.sp
|
68 |
The function \fBregcomp()\fR is called to compile a pattern into an
|
69 |
internal form. The pattern is a C string terminated by a binary zero, and
|
70 |
is passed in the argument \fIpattern\fR. The \fIpreg\fR argument is a pointer
|
71 |
to a regex_t structure which is used as a base for storing information about
|
72 |
the compiled expression.
|
73 |
|
74 |
The argument \fIcflags\fR is either zero, or contains one or more of the bits
|
75 |
defined by the following macros:
|
76 |
|
77 |
REG_ICASE
|
78 |
|
79 |
The PCRE_CASELESS option is set when the expression is passed for compilation
|
80 |
to the native function.
|
81 |
|
82 |
REG_NEWLINE
|
83 |
|
84 |
The PCRE_MULTILINE option is set when the expression is passed for compilation
|
85 |
to the native function. Note that this does \fInot\fR mimic the defined POSIX
|
86 |
behaviour for REG_NEWLINE (see the following section).
|
87 |
|
88 |
In the absence of these flags, no options are passed to the native function.
|
89 |
This means the the regex is compiled with PCRE default semantics. In
|
90 |
particular, the way it handles newline characters in the subject string is the
|
91 |
Perl way, not the POSIX way. Note that setting PCRE_MULTILINE has only
|
92 |
\fIsome\fR of the effects specified for REG_NEWLINE. It does not affect the way
|
93 |
newlines are matched by . (they aren't) or by a negative class such as [^a]
|
94 |
(they are).
|
95 |
|
96 |
The yield of \fBregcomp()\fR is zero on success, and non-zero otherwise. The
|
97 |
\fIpreg\fR structure is filled in on success, and one member of the structure
|
98 |
is public: \fIre_nsub\fR contains the number of capturing subpatterns in
|
99 |
the regular expression. Various error codes are defined in the header file.
|
100 |
|
101 |
.SH MATCHING NEWLINE CHARACTERS
|
102 |
.rs
|
103 |
.sp
|
104 |
This area is not simple, because POSIX and Perl take different views of things.
|
105 |
It is not possible to get PCRE to obey POSIX semantics, but then PCRE was never
|
106 |
intended to be a POSIX engine. The following table lists the different
|
107 |
possibilities for matching newline characters in PCRE:
|
108 |
|
109 |
Default Change with
|
110 |
|
111 |
. matches newline no PCRE_DOTALL
|
112 |
newline matches [^a] yes not changeable
|
113 |
$ matches \\n at end yes PCRE_DOLLARENDONLY
|
114 |
$ matches \\n in middle no PCRE_MULTILINE
|
115 |
^ matches \\n in middle no PCRE_MULTILINE
|
116 |
|
117 |
This is the equivalent table for POSIX:
|
118 |
|
119 |
Default Change with
|
120 |
|
121 |
. matches newline yes REG_NEWLINE
|
122 |
newline matches [^a] yes REG_NEWLINE
|
123 |
$ matches \\n at end no REG_NEWLINE
|
124 |
$ matches \\n in middle no REG_NEWLINE
|
125 |
^ matches \\n in middle no REG_NEWLINE
|
126 |
|
127 |
PCRE's behaviour is the same as Perl's, except that there is no equivalent for
|
128 |
PCRE_DOLLARENDONLY in Perl. In both PCRE and Perl, there is no way to stop
|
129 |
newline from matching [^a].
|
130 |
|
131 |
The default POSIX newline handling can be obtained by setting PCRE_DOTALL and
|
132 |
PCRE_DOLLARENDONLY, but there is no way to make PCRE behave exactly as for the
|
133 |
REG_NEWLINE action.
|
134 |
|
135 |
.SH MATCHING A PATTERN
|
136 |
.rs
|
137 |
.sp
|
138 |
The function \fBregexec()\fR is called to match a pre-compiled pattern
|
139 |
\fIpreg\fR against a given \fIstring\fR, which is terminated by a zero byte,
|
140 |
subject to the options in \fIeflags\fR. These can be:
|
141 |
|
142 |
REG_NOTBOL
|
143 |
|
144 |
The PCRE_NOTBOL option is set when calling the underlying PCRE matching
|
145 |
function.
|
146 |
|
147 |
REG_NOTEOL
|
148 |
|
149 |
The PCRE_NOTEOL option is set when calling the underlying PCRE matching
|
150 |
function.
|
151 |
|
152 |
The portion of the string that was matched, and also any captured substrings,
|
153 |
are returned via the \fIpmatch\fR argument, which points to an array of
|
154 |
\fInmatch\fR structures of type \fIregmatch_t\fR, containing the members
|
155 |
\fIrm_so\fR and \fIrm_eo\fR. These contain the offset to the first character of
|
156 |
each substring and the offset to the first character after the end of each
|
157 |
substring, respectively. The 0th element of the vector relates to the entire
|
158 |
portion of \fIstring\fR that was matched; subsequent elements relate to the
|
159 |
capturing subpatterns of the regular expression. Unused entries in the array
|
160 |
have both structure members set to -1.
|
161 |
|
162 |
A successful match yields a zero return; various error codes are defined in the
|
163 |
header file, of which REG_NOMATCH is the "expected" failure code.
|
164 |
|
165 |
.SH ERROR MESSAGES
|
166 |
.rs
|
167 |
.sp
|
168 |
The \fBregerror()\fR function maps a non-zero errorcode from either
|
169 |
\fBregcomp()\fR or \fBregexec()\fR to a printable message. If \fIpreg\fR is not
|
170 |
NULL, the error should have arisen from the use of that structure. A message
|
171 |
terminated by a binary zero is placed in \fIerrbuf\fR. The length of the
|
172 |
message, including the zero, is limited to \fIerrbuf_size\fR. The yield of the
|
173 |
function is the size of buffer needed to hold the whole message.
|
174 |
|
175 |
.SH STORAGE
|
176 |
.rs
|
177 |
.sp
|
178 |
Compiling a regular expression causes memory to be allocated and associated
|
179 |
with the \fIpreg\fR structure. The function \fBregfree()\fR frees all such
|
180 |
memory, after which \fIpreg\fR may no longer be used as a compiled expression.
|
181 |
|
182 |
.SH AUTHOR
|
183 |
.rs
|
184 |
.sp
|
185 |
Philip Hazel <ph10@cam.ac.uk>
|
186 |
.br
|
187 |
University Computing Service,
|
188 |
.br
|
189 |
Cambridge CB2 3QG, England.
|
190 |
|
191 |
.in 0
|
192 |
Last updated: 03 February 2003
|
193 |
.br
|
194 |
Copyright (c) 1997-2003 University of Cambridge.
|