Penguin
Recent Changes
Annotated edit history of regcomp(3) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 REGCOMP
2 !!!REGCOMP
3 NAME
4 SYNOPSIS
5 POSIX REGEX COMPILING
6 POSIX REGEX MATCHING
7 POSIX ERROR REPORTING
8 POSIX PATTERN BUFFER FREEING
9 RETURN VALUE
10 ERRORS
11 CONFORMING TO
12 SEE ALSO
13 ----
14 !!NAME
15
16
17 regcomp, regexec, regerror, regfree - POSIX regex functions
18 !!SYNOPSIS
19
20
21 __#include __
22 #include __
23
24
25 __int regcomp(regex_t *__''preg''__, const char
26 *__''regex''__, int__
27 ''cflags''__);__
28
29
30 __int regexec(const regex_t *__''preg''__, const char
31 *__''string''__, size_t__ ''nmatch''__,
32 regmatch_t__ ''pmatch[[]''__, int__
33 ''eflags''__);__
34
35
36 __size_t regerror(int__ ''errcode''__, const regex_t
37 *__''preg''__, char *__''errbuf''__, size_t__
38 ''errbuf_size''__);__
39
40
41 __void regfree(regex_t
42 *__''preg''__);__
43 !!POSIX REGEX COMPILING
44
45
46 __regcomp__ is used to compile a regular expression into
47 a form that is suitable for subsequent __regexec__
48 searches.
49
50
51 __regcomp__ is supplied with ''preg'', a pointer to a
52 pattern buffer storage area; ''regex'', a pointer to the
53 null-terminated string and ''cflags'', flags used to
54 determine the type of compilation.
55
56
57 All regular expression searching must be done via a compiled
58 pattern buffer, thus __regexec__ must always be supplied
59 with the address of a __regcomp__ initialised pattern
60 buffer.
61
62
63 ''cflags'' may be the bitwise-__or__ of one or more of
64 the following:
65
66
67 __REG_EXTENDED__
68
69
70 Use __POSIX__ Extended Regular Expression syntax when
71 interpreting ''regex''. If not set, __POSIX__ Basic
72 Regular Expression syntax is used.
73
74
75 __REG_ICASE__
76
77
78 Do not differentiate case. Subsequent __regexec__
79 searches using this pattern buffer will be case
80 insensitive.
81
82
83 __REG_NOSUB__
84
85
86 Support for substring addressing of matches is not required.
87 The ''nmatch'' and ''pmatch'' parameters to
88 __regexec__ are ignored if the pattern buffer supplied
89 was compiled with this flag set.
90
91
92 __REG_NEWLINE__
93
94
95 Match-any-character operators don't match a
96 newline.
97
98
99 A non-matching list (__[[^...]__) not containing a newline
100 does not match a newline.
101
102
103 Match-beginning-of-line operator (__^__) matches the
104 empty string immediately after a newline, regardless of
105 whether ''eflags'', the execution flags of
106 __regexec__, contains __REG_NOTBOL__.
107
108
109 Match-end-of-line operator (__$__) matches the empty
110 string immediately before a newline, regardless of whether
111 ''eflags'' contains __REG_NOTEOL__.
112 !!POSIX REGEX MATCHING
113
114
115 __regexec__ is used to match a null-terminated string
116 against the precompiled pattern buffer, ''preg''.
117 ''nmatch'' and ''pmatch'' are used to provide
118 information regarding the location of any matches.
119 ''eflags'' may be the bitwise-__or__ of one or both of
120 __REG_NOTBOL__ and __REG_NOTEOL__ which cause changes
121 in matching behaviour described below.
122
123
124 __REG_NOTBOL__
125
126
127 The match-beginning-of-line operator always fails to match
128 (but see the compilation flag __REG_NEWLINE__ above) This
129 flag may be used when different portions of a string are
130 passed to __regexec__ and the beginning of the string
131 should not be interpreted as the beginning of the
132 line.
133
134
135 __REG_NOTEOL__
136
137
138 The match-end-of-line operator always fails to match (but
139 see the compilation flag __REG_NEWLINE__
140 above)
141
142
143 __BYTE OFFSETS__
144
145
146 Unless __REG_NOSUB__ was set for the compilation of the
147 pattern buffer, it is possible to obtain substring match
148 addressing information. ''pmatch'' must be dimensioned to
149 have at least ''nmatch'' elements. These are filled in by
150 __regexec__ with substring match addresses. Any unused
151 structure elements will contain the value -1.
152
153
154 The __regmatch_t__ structure which is the type of
155 ''pmatch'' is defined in ''regex.h''.
156
157
158 __typedef struct
159 {
160 regoff_t__ ''rm_so''__;
161 regoff_t__ ''rm_eo''__;
162 } regmatch_t;__
163
164
165 Each ''rm_so'' element that is not -1 indicates the start
166 offset of the next largest substring match within the
167 string. The relative ''rm_eo'' element indicates the end
168 offset of the match.
169 !!POSIX ERROR REPORTING
170
171
172 __regerror__ is used to turn the error codes that can be
173 returned by both __regcomp__ and __regexec__ into
174 error message strings.
175
176
177 __regerror__ is passed the error code, ''errcode'',
178 the pattern buffer, ''preg'', a pointer to a character
179 string buffer, ''errbuf'', and the size of the string
180 buffer, ''errbuf_size''. It returns the size of the
181 ''errbuf'' required to contain the null-terminated error
182 message string. If both ''errbuf'' and ''errbuf_size''
183 are non-zero, ''errbuf'' is filled in with the first
184 ''errbuf_size - 1'' characters of the error message and a
185 terminating null.
186 !!POSIX PATTERN BUFFER FREEING
187
188
189 Supplying __regfree__ with a precompiled pattern buffer,
190 ''preg'' will free the memory allocated to the pattern
191 buffer by the compiling process,
192 __regcomp__.
193 !!RETURN VALUE
194
195
196 __regcomp__ returns zero for a successful compilation or
197 an error code for failure.
198
199
200 __regexec__ returns zero for a successful match or
201 __REG_NOMATCH__ for failure.
202 !!ERRORS
203
204
205 The following errors can be returned by
206 __regcomp__:
207
208
209 __REG_BADRPT__
210
211
212 Invalid use of repetition operators such as using `__*__'
213 as the first character.
214
215
216 __REG_BADBR__
217
218
219 Invalid use of back reference operator.
220
221
222 __REG_EBRACE__
223
224
225 Un-matched brace interval operators.
226
227
228 __REG_EBRACK__
229
230
231 Un-matched bracket list operators.
232
233
234 __REG_ERANGE__
235
236
237 Invalid use of the range operator, eg. the ending point of
238 the range occurs prior to the starting point.
239
240
241 __REG_ECTYPE__
242
243
244 Unknown character class name.
245
246
247 __REG_ECOLLATE__
248
249
250 Invalid collating element.
251
252
253 __REG_EPAREN__
254
255
256 Un-matched parenthesis group operators.
257
258
259 __REG_ESUBREG__
260
261
262 Invalid back reference to a subexpression.
263
264
265 __REG_EEND__
266
267
268 Non specific error. This is not defined by
269 POSIX.2.
270
271
272 __REG_EESCAPE__
273
274
275 Trailing backslash.
276
277
278 __REG_BADPAT__
279
280
281 Invalid use of pattern operators such as group or
282 list.
283
284
285 __REG_ESIZE__
286
287
288 Compiled regular expression requires a pattern buffer larger
289 than 64Kb. This is not defined by POSIX.2.
290
291
292 __REG_ESPACE__
293
294
295 The regex routines ran out of memory.
296 !!CONFORMING TO
297
298
299 POSIX.2
300 !!SEE ALSO
301
302
303 regex(7), __GNU regex manual__
304 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.