/[pcre]/code/trunk/doc/pcreposix.3
ViewVC logotype

Contents of /code/trunk/doc/pcreposix.3

Parent Directory Parent Directory | Revision Log Revision Log


Revision 93 - (hide annotations) (download)
Sat Feb 24 21:41:42 2007 UTC (7 years, 5 months ago) by nigel
File size: 8664 byte(s)
Load pcre-7.0 into code/trunk.

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

webmaster@exim.org
ViewVC Help
Powered by ViewVC 1.1.12