← Back to branch summary

~ubuntu-branches/ubuntu/precise/mysql-5.1/precise

« back to all changes in this revision

Viewing changes to regex/regex.3

  • Committer: Bazaar Package Importer
  • Author(s): Norbert Tretkowski
  • Date: 2010-03-17 14:56:02 UTC
  • Revision ID: james.westby@ubuntu.com-20100317145602-x7e30l1b2sb5s6w6
Tags: upstream-5.1.45
Import upstream version 5.1.45

Show diffs side-by-side

added added

removed removed

Lines of Context:
regex/regex.3
 
1
.TH REGEX 3 "17 May 1993"
 
2
.BY "Henry Spencer"
 
3
.de ZR
 
4
.\" one other place knows this name:  the SEE ALSO section
 
5
.IR regex (7) \\$1
 
6
..
 
7
.SH NAME
 
8
regcomp, regexec, regerror, regfree \- regular-expression library
 
9
.SH SYNOPSIS
 
10
.ft B
 
11
.\".na
 
12
#include <sys/types.h>
 
13
.br
 
14
#include <regex.h>
 
15
.HP 10
 
16
int regcomp(regex_t\ *preg, const\ char\ *pattern, int\ cflags);
 
17
.HP
 
18
int\ regexec(const\ regex_t\ *preg, const\ char\ *string,
 
19
size_t\ nmatch, regmatch_t\ pmatch[], int\ eflags);
 
20
.HP
 
21
size_t\ regerror(int\ errcode, const\ regex_t\ *preg,
 
22
char\ *errbuf, size_t\ errbuf_size);
 
23
.HP
 
24
void\ regfree(regex_t\ *preg);
 
25
.\".ad
 
26
.ft
 
27
.SH DESCRIPTION
 
28
These routines implement POSIX 1003.2 regular expressions (``RE''s);
 
29
see
 
30
.ZR .
 
31
.I Regcomp
 
32
compiles an RE written as a string into an internal form,
 
33
.I regexec
 
34
matches that internal form against a string and reports results,
 
35
.I regerror
 
36
transforms error codes from either into human-readable messages,
 
37
and
 
38
.I regfree
 
39
frees any dynamically-allocated storage used by the internal form
 
40
of an RE.
 
41
.PP
 
42
The header
 
43
.I <regex.h>
 
44
declares two structure types,
 
45
.I regex_t
 
46
and
 
47
.IR regmatch_t ,
 
48
the former for compiled internal forms and the latter for match reporting.
 
49
It also declares the four functions,
 
50
a type
 
51
.IR regoff_t ,
 
52
and a number of constants with names starting with ``REG_''.
 
53
.PP
 
54
.I Regcomp
 
55
compiles the regular expression contained in the
 
56
.I pattern
 
57
string,
 
58
subject to the flags in
 
59
.IR cflags ,
 
60
and places the results in the
 
61
.I regex_t
 
62
structure pointed to by
 
63
.IR preg .
 
64
.I Cflags
 
65
is the bitwise OR of zero or more of the following flags:
 
66
.IP REG_EXTENDED \w'REG_EXTENDED'u+2n
 
67
Compile modern (``extended'') REs,
 
68
rather than the obsolete (``basic'') REs that
 
69
are the default.
 
70
.IP REG_BASIC
 
71
This is a synonym for 0,
 
72
provided as a counterpart to REG_EXTENDED to improve readability.
 
73
.IP REG_NOSPEC
 
74
Compile with recognition of all special characters turned off.
 
75
All characters are thus considered ordinary,
 
76
so the ``RE'' is a literal string.
 
77
This is an extension,
 
78
compatible with but not specified by POSIX 1003.2,
 
79
and should be used with
 
80
caution in software intended to be portable to other systems.
 
81
REG_EXTENDED and REG_NOSPEC may not be used
 
82
in the same call to
 
83
.IR regcomp .
 
84
.IP REG_ICASE
 
85
Compile for matching that ignores upper/lower case distinctions.
 
86
See
 
87
.ZR .
 
88
.IP REG_NOSUB
 
89
Compile for matching that need only report success or failure,
 
90
not what was matched.
 
91
.IP REG_NEWLINE
 
92
Compile for newline-sensitive matching.
 
93
By default, newline is a completely ordinary character with no special
 
94
meaning in either REs or strings.
 
95
With this flag,
 
96
`[^' bracket expressions and `.' never match newline,
 
97
a `^' anchor matches the null string after any newline in the string
 
98
in addition to its normal function,
 
99
and the `$' anchor matches the null string before any newline in the
 
100
string in addition to its normal function.
 
101
.IP REG_PEND
 
102
The regular expression ends,
 
103
not at the first NUL,
 
104
but just before the character pointed to by the
 
105
.I re_endp
 
106
member of the structure pointed to by
 
107
.IR preg .
 
108
The
 
109
.I re_endp
 
110
member is of type
 
111
.IR const\ char\ * .
 
112
This flag permits inclusion of NULs in the RE;
 
113
they are considered ordinary characters.
 
114
This is an extension,
 
115
compatible with but not specified by POSIX 1003.2,
 
116
and should be used with
 
117
caution in software intended to be portable to other systems.
 
118
.PP
 
119
When successful,
 
120
.I regcomp
 
121
returns 0 and fills in the structure pointed to by
 
122
.IR preg .
 
123
One member of that structure
 
124
(other than
 
125
.IR re_endp )
 
126
is publicized:
 
127
.IR re_nsub ,
 
128
of type
 
129
.IR size_t ,
 
130
contains the number of parenthesized subexpressions within the RE
 
131
(except that the value of this member is undefined if the
 
132
REG_NOSUB flag was used).
 
133
If
 
134
.I regcomp
 
135
fails, it returns a non-zero error code;
 
136
see DIAGNOSTICS.
 
137
.PP
 
138
.I Regexec
 
139
matches the compiled RE pointed to by
 
140
.I preg
 
141
against the
 
142
.IR string ,
 
143
subject to the flags in
 
144
.IR eflags ,
 
145
and reports results using
 
146
.IR nmatch ,
 
147
.IR pmatch ,
 
148
and the returned value.
 
149
The RE must have been compiled by a previous invocation of
 
150
.IR regcomp .
 
151
The compiled form is not altered during execution of
 
152
.IR regexec ,
 
153
so a single compiled RE can be used simultaneously by multiple threads.
 
154
.PP
 
155
By default,
 
156
the NUL-terminated string pointed to by
 
157
.I string
 
158
is considered to be the text of an entire line, minus any terminating
 
159
newline.
 
160
The
 
161
.I eflags
 
162
argument is the bitwise OR of zero or more of the following flags:
 
163
.IP REG_NOTBOL \w'REG_STARTEND'u+2n
 
164
The first character of
 
165
the string
 
166
is not the beginning of a line, so the `^' anchor should not match before it.
 
167
This does not affect the behavior of newlines under REG_NEWLINE.
 
168
.IP REG_NOTEOL
 
169
The NUL terminating
 
170
the string
 
171
does not end a line, so the `$' anchor should not match before it.
 
172
This does not affect the behavior of newlines under REG_NEWLINE.
 
173
.IP REG_STARTEND
 
174
The string is considered to start at
 
175
\fIstring\fR\ + \fIpmatch\fR[0].\fIrm_so\fR
 
176
and to have a terminating NUL located at
 
177
\fIstring\fR\ + \fIpmatch\fR[0].\fIrm_eo\fR
 
178
(there need not actually be a NUL at that location),
 
179
regardless of the value of
 
180
.IR nmatch .
 
181
See below for the definition of
 
182
.IR pmatch
 
183
and
 
184
.IR nmatch .
 
185
This is an extension,
 
186
compatible with but not specified by POSIX 1003.2,
 
187
and should be used with
 
188
caution in software intended to be portable to other systems.
 
189
Note that a non-zero \fIrm_so\fR does not imply REG_NOTBOL;
 
190
REG_STARTEND affects only the location of the string,
 
191
not how it is matched.
 
192
.PP
 
193
See
 
194
.ZR
 
195
for a discussion of what is matched in situations where an RE or a
 
196
portion thereof could match any of several substrings of
 
197
.IR string .
 
198
.PP
 
199
Normally,
 
200
.I regexec
 
201
returns 0 for success and the non-zero code REG_NOMATCH for failure.
 
202
Other non-zero error codes may be returned in exceptional situations;
 
203
see DIAGNOSTICS.
 
204
.PP
 
205
If REG_NOSUB was specified in the compilation of the RE,
 
206
or if
 
207
.I nmatch
 
208
is 0,
 
209
.I regexec
 
210
ignores the
 
211
.I pmatch
 
212
argument (but see below for the case where REG_STARTEND is specified).
 
213
Otherwise,
 
214
.I pmatch
 
215
points to an array of
 
216
.I nmatch
 
217
structures of type
 
218
.IR regmatch_t .
 
219
Such a structure has at least the members
 
220
.I rm_so
 
221
and
 
222
.IR rm_eo ,
 
223
both of type
 
224
.I regoff_t
 
225
(a signed arithmetic type at least as large as an
 
226
.I off_t
 
227
and a
 
228
.IR ssize_t ),
 
229
containing respectively the offset of the first character of a substring
 
230
and the offset of the first character after the end of the substring.
 
231
Offsets are measured from the beginning of the
 
232
.I string
 
233
argument given to
 
234
.IR regexec .
 
235
An empty substring is denoted by equal offsets,
 
236
both indicating the character following the empty substring.
 
237
.PP
 
238
The 0th member of the
 
239
.I pmatch
 
240
array is filled in to indicate what substring of
 
241
.I string
 
242
was matched by the entire RE.
 
243
Remaining members report what substring was matched by parenthesized
 
244
subexpressions within the RE;
 
245
member
 
246
.I i
 
247
reports subexpression
 
248
.IR i ,
 
249
with subexpressions counted (starting at 1) by the order of their opening
 
250
parentheses in the RE, left to right.
 
251
Unused entries in the array\(emcorresponding either to subexpressions that
 
252
did not participate in the match at all, or to subexpressions that do not
 
253
exist in the RE (that is, \fIi\fR\ > \fIpreg\fR\->\fIre_nsub\fR)\(emhave both
 
254
.I rm_so
 
255
and
 
256
.I rm_eo
 
257
set to \-1.
 
258
If a subexpression participated in the match several times,
 
259
the reported substring is the last one it matched.
 
260
(Note, as an example in particular, that when the RE `(b*)+' matches `bbb',
 
261
the parenthesized subexpression matches each of the three `b's and then
 
262
an infinite number of empty strings following the last `b',
 
263
so the reported substring is one of the empties.)
 
264
.PP
 
265
If REG_STARTEND is specified,
 
266
.I pmatch
 
267
must point to at least one
 
268
.I regmatch_t
 
269
(even if
 
270
.I nmatch
 
271
is 0 or REG_NOSUB was specified),
 
272
to hold the input offsets for REG_STARTEND.
 
273
Use for output is still entirely controlled by
 
274
.IR nmatch ;
 
275
if
 
276
.I nmatch
 
277
is 0 or REG_NOSUB was specified,
 
278
the value of
 
279
.IR pmatch [0]
 
280
will not be changed by a successful
 
281
.IR regexec .
 
282
.PP
 
283
.I Regerror
 
284
maps a non-zero
 
285
.I errcode
 
286
from either
 
287
.I regcomp
 
288
or
 
289
.I regexec
 
290
to a human-readable, printable message.
 
291
If
 
292
.I preg
 
293
is non-NULL,
 
294
the error code should have arisen from use of
 
295
the
 
296
.I regex_t
 
297
pointed to by
 
298
.IR preg ,
 
299
and if the error code came from
 
300
.IR regcomp ,
 
301
it should have been the result from the most recent
 
302
.I regcomp
 
303
using that
 
304
.IR regex_t .
 
305
.RI ( Regerror
 
306
may be able to supply a more detailed message using information
 
307
from the
 
308
.IR regex_t .)
 
309
.I Regerror
 
310
places the NUL-terminated message into the buffer pointed to by
 
311
.IR errbuf ,
 
312
limiting the length (including the NUL) to at most
 
313
.I errbuf_size
 
314
bytes.
 
315
If the whole message won't fit,
 
316
as much of it as will fit before the terminating NUL is supplied.
 
317
In any case,
 
318
the returned value is the size of buffer needed to hold the whole
 
319
message (including terminating NUL).
 
320
If
 
321
.I errbuf_size
 
322
is 0,
 
323
.I errbuf
 
324
is ignored but the return value is still correct.
 
325
.PP
 
326
If the
 
327
.I errcode
 
328
given to
 
329
.I regerror
 
330
is first ORed with REG_ITOA,
 
331
the ``message'' that results is the printable name of the error code,
 
332
e.g. ``REG_NOMATCH'',
 
333
rather than an explanation thereof.
 
334
If
 
335
.I errcode
 
336
is REG_ATOI,
 
337
then
 
338
.I preg
 
339
shall be non-NULL and the
 
340
.I re_endp
 
341
member of the structure it points to
 
342
must point to the printable name of an error code;
 
343
in this case, the result in
 
344
.I errbuf
 
345
is the decimal digits of
 
346
the numeric value of the error code
 
347
(0 if the name is not recognized).
 
348
REG_ITOA and REG_ATOI are intended primarily as debugging facilities;
 
349
they are extensions,
 
350
compatible with but not specified by POSIX 1003.2,
 
351
and should be used with
 
352
caution in software intended to be portable to other systems.
 
353
Be warned also that they are considered experimental and changes are possible.
 
354
.PP
 
355
.I Regfree
 
356
frees any dynamically-allocated storage associated with the compiled RE
 
357
pointed to by
 
358
.IR preg .
 
359
The remaining
 
360
.I regex_t
 
361
is no longer a valid compiled RE
 
362
and the effect of supplying it to
 
363
.I regexec
 
364
or
 
365
.I regerror
 
366
is undefined.
 
367
.PP
 
368
None of these functions references global variables except for tables
 
369
of constants;
 
370
all are safe for use from multiple threads if the arguments are safe.
 
371
.SH IMPLEMENTATION CHOICES
 
372
There are a number of decisions that 1003.2 leaves up to the implementor,
 
373
either by explicitly saying ``undefined'' or by virtue of them being
 
374
forbidden by the RE grammar.
 
375
This implementation treats them as follows.
 
376
.PP
 
377
See
 
378
.ZR
 
379
for a discussion of the definition of case-independent matching.
 
380
.PP
 
381
There is no particular limit on the length of REs,
 
382
except insofar as memory is limited.
 
383
Memory usage is approximately linear in RE size, and largely insensitive
 
384
to RE complexity, except for bounded repetitions.
 
385
See BUGS for one short RE using them
 
386
that will run almost any system out of memory.
 
387
.PP
 
388
A backslashed character other than one specifically given a magic meaning
 
389
by 1003.2 (such magic meanings occur only in obsolete [``basic''] REs)
 
390
is taken as an ordinary character.
 
391
.PP
 
392
Any unmatched [ is a REG_EBRACK error.
 
393
.PP
 
394
Equivalence classes cannot begin or end bracket-expression ranges.
 
395
The endpoint of one range cannot begin another.
 
396
.PP
 
397
RE_DUP_MAX, the limit on repetition counts in bounded repetitions, is 255.
 
398
.PP
 
399
A repetition operator (?, *, +, or bounds) cannot follow another
 
400
repetition operator.
 
401
A repetition operator cannot begin an expression or subexpression
 
402
or follow `^' or `|'.
 
403
.PP
 
404
`|' cannot appear first or last in a (sub)expression or after another `|',
 
405
i.e. an operand of `|' cannot be an empty subexpression.
 
406
An empty parenthesized subexpression, `()', is legal and matches an
 
407
empty (sub)string.
 
408
An empty string is not a legal RE.
 
409
.PP
 
410
A `{' followed by a digit is considered the beginning of bounds for a
 
411
bounded repetition, which must then follow the syntax for bounds.
 
412
A `{' \fInot\fR followed by a digit is considered an ordinary character.
 
413
.PP
 
414
`^' and `$' beginning and ending subexpressions in obsolete (``basic'')
 
415
REs are anchors, not ordinary characters.
 
416
.SH SEE ALSO
 
417
grep(1), regex(7)
 
418
.PP
 
419
POSIX 1003.2, sections 2.8 (Regular Expression Notation)
 
420
and
 
421
B.5 (C Binding for Regular Expression Matching).
 
422
.SH DIAGNOSTICS
 
423
Non-zero error codes from
 
424
.I regcomp
 
425
and
 
426
.I regexec
 
427
include the following:
 
428
.PP
 
429
.nf
 
430
.ta \w'REG_ECOLLATE'u+3n
 
431
REG_NOMATCH     regexec() failed to match
 
432
REG_BADPAT      invalid regular expression
 
433
REG_ECOLLATE    invalid collating element
 
434
REG_ECTYPE      invalid character class
 
435
REG_EESCAPE     \e applied to unescapable character
 
436
REG_ESUBREG     invalid backreference number
 
437
REG_EBRACK      brackets [ ] not balanced
 
438
REG_EPAREN      parentheses ( ) not balanced
 
439
REG_EBRACE      braces { } not balanced
 
440
REG_BADBR       invalid repetition count(s) in { }
 
441
REG_ERANGE      invalid character range in [ ]
 
442
REG_ESPACE      ran out of memory
 
443
REG_BADRPT      ?, *, or + operand invalid
 
444
REG_EMPTY       empty (sub)expression
 
445
REG_ASSERT      ``can't happen''\(emyou found a bug
 
446
REG_INVARG      invalid argument, e.g. negative-length string
 
447
.fi
 
448
.SH HISTORY
 
449
Written by Henry Spencer at University of Toronto,
 
450
henry@zoo.toronto.edu.
 
451
.SH BUGS
 
452
This is an alpha release with known defects.
 
453
Please report problems.
 
454
.PP
 
455
There is one known functionality bug.
 
456
The implementation of internationalization is incomplete:
 
457
the locale is always assumed to be the default one of 1003.2,
 
458
and only the collating elements etc. of that locale are available.
 
459
.PP
 
460
The back-reference code is subtle and doubts linger about its correctness
 
461
in complex cases.
 
462
.PP
 
463
.I Regexec
 
464
performance is poor.
 
465
This will improve with later releases.
 
466
.I Nmatch
 
467
exceeding 0 is expensive;
 
468
.I nmatch
 
469
exceeding 1 is worse.
 
470
.I Regexec
 
471
is largely insensitive to RE complexity \fIexcept\fR that back
 
472
references are massively expensive.
 
473
RE length does matter; in particular, there is a strong speed bonus
 
474
for keeping RE length under about 30 characters,
 
475
with most special characters counting roughly double.
 
476
.PP
 
477
.I Regcomp
 
478
implements bounded repetitions by macro expansion,
 
479
which is costly in time and space if counts are large
 
480
or bounded repetitions are nested.
 
481
An RE like, say,
 
482
`((((a{1,100}){1,100}){1,100}){1,100}){1,100}'
 
483
will (eventually) run almost any existing machine out of swap space.
 
484
.PP
 
485
There are suspected problems with response to obscure error conditions.
 
486
Notably,
 
487
certain kinds of internal overflow,
 
488
produced only by truly enormous REs or by multiply nested bounded repetitions,
 
489
are probably not handled well.
 
490
.PP
 
491
Due to a mistake in 1003.2, things like `a)b' are legal REs because `)' is
 
492
a special character only in the presence of a previous unmatched `('.
 
493
This can't be fixed until the spec is fixed.
 
494
.PP
 
495
The standard's definition of back references is vague.
 
496
For example, does
 
497
`a\e(\e(b\e)*\e2\e)*d' match `abbbd'?
 
498
Until the standard is clarified,
 
499
behavior in such cases should not be relied on.
 
500
.PP
 
501
The implementation of word-boundary matching is a bit of a kludge,
 
502
and bugs may lurk in combinations of word-boundary matching and anchoring.