1 .\" $NetBSD: regex.3,v 1.1.1.2 2008/05/18 14:31:38 aymeric Exp $
3 .\" Copyright (c) 1992, 1993, 1994 Henry Spencer.
4 .\" Copyright (c) 1992, 1993, 1994
5 .\" The Regents of the University of California. All rights reserved.
7 .\" This code is derived from software contributed to Berkeley by
8 .\" Henry Spencer of the University of Toronto.
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
13 .\" 1. Redistributions of source code must retain the above copyright
14 .\" notice, this list of conditions and the following disclaimer.
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in the
17 .\" documentation and/or other materials provided with the distribution.
18 .\" 3. All advertising materials mentioning features or use of this software
19 .\" must display the following acknowledgement:
20 .\" This product includes software developed by the University of
21 .\" California, Berkeley and its contributors.
22 .\" 4. Neither the name of the University nor the names of its contributors
23 .\" may be used to endorse or promote products derived from this software
24 .\" without specific prior written permission.
26 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
27 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
28 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
29 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
30 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
31 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
32 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
33 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
34 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
35 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
38 .\" @(#)regex.3 8.2 (Berkeley) 3/16/94
40 .TH REGEX 3 "March 16, 1994"
42 .\" one other place knows this name: the SEE ALSO section
43 .IR re_format (7) \\$1
46 regcomp, regexec, regerror, regfree \- regular-expression library
50 #include <sys/types.h>
54 int regcomp(regex_t\ *preg, const\ char\ *pattern, int\ cflags);
56 int\ regexec(const\ regex_t\ *preg, const\ char\ *string,
57 size_t\ nmatch, regmatch_t\ pmatch[], int\ eflags);
59 size_t\ regerror(int\ errcode, const\ regex_t\ *preg,
60 char\ *errbuf, size_t\ errbuf_size);
62 void\ regfree(regex_t\ *preg);
66 These routines implement POSIX 1003.2 regular expressions (``RE''s);
70 compiles an RE written as a string into an internal form,
72 matches that internal form against a string and reports results,
74 transforms error codes from either into human-readable messages,
77 frees any dynamically-allocated storage used by the internal form
82 declares two structure types,
86 the former for compiled internal forms and the latter for match reporting.
87 It also declares the four functions,
90 and a number of constants with names starting with ``REG_''.
93 compiles the regular expression contained in the
96 subject to the flags in
98 and places the results in the
100 structure pointed to by
103 is the bitwise OR of zero or more of the following flags:
104 .IP REG_EXTENDED \w'REG_EXTENDED'u+2n
105 Compile modern (``extended'') REs,
106 rather than the obsolete (``basic'') REs that
109 This is a synonym for 0,
110 provided as a counterpart to REG_EXTENDED to improve readability.
112 Compile with recognition of all special characters turned off.
113 All characters are thus considered ordinary,
114 so the ``RE'' is a literal string.
115 This is an extension,
116 compatible with but not specified by POSIX 1003.2,
117 and should be used with
118 caution in software intended to be portable to other systems.
119 REG_EXTENDED and REG_NOSPEC may not be used
123 Compile for matching that ignores upper/lower case distinctions.
127 Compile for matching that need only report success or failure,
128 not what was matched.
130 Compile for newline-sensitive matching.
131 By default, newline is a completely ordinary character with no special
132 meaning in either REs or strings.
134 `[^' bracket expressions and `.' never match newline,
135 a `^' anchor matches the null string after any newline in the string
136 in addition to its normal function,
137 and the `$' anchor matches the null string before any newline in the
138 string in addition to its normal function.
140 The regular expression ends,
141 not at the first NUL,
142 but just before the character pointed to by the
144 member of the structure pointed to by
150 This flag permits inclusion of NULs in the RE;
151 they are considered ordinary characters.
152 This is an extension,
153 compatible with but not specified by POSIX 1003.2,
154 and should be used with
155 caution in software intended to be portable to other systems.
159 returns 0 and fills in the structure pointed to by
161 One member of that structure
168 contains the number of parenthesized subexpressions within the RE
169 (except that the value of this member is undefined if the
170 REG_NOSUB flag was used).
173 fails, it returns a non-zero error code;
177 matches the compiled RE pointed to by
181 subject to the flags in
183 and reports results using
186 and the returned value.
187 The RE must have been compiled by a previous invocation of
189 The compiled form is not altered during execution of
191 so a single compiled RE can be used simultaneously by multiple threads.
194 the NUL-terminated string pointed to by
196 is considered to be the text of an entire line, minus any terminating
200 argument is the bitwise OR of zero or more of the following flags:
201 .IP REG_NOTBOL \w'REG_STARTEND'u+2n
202 The first character of
204 is not the beginning of a line, so the `^' anchor should not match before it.
205 This does not affect the behavior of newlines under REG_NEWLINE.
209 does not end a line, so the `$' anchor should not match before it.
210 This does not affect the behavior of newlines under REG_NEWLINE.
212 The string is considered to start at
213 \fIstring\fR\ + \fIpmatch\fR[0].\fIrm_so\fR
214 and to have a terminating NUL located at
215 \fIstring\fR\ + \fIpmatch\fR[0].\fIrm_eo\fR
216 (there need not actually be a NUL at that location),
217 regardless of the value of
219 See below for the definition of
223 This is an extension,
224 compatible with but not specified by POSIX 1003.2,
225 and should be used with
226 caution in software intended to be portable to other systems.
227 Note that a non-zero \fIrm_so\fR does not imply REG_NOTBOL;
228 REG_STARTEND affects only the location of the string,
229 not how it is matched.
233 for a discussion of what is matched in situations where an RE or a
234 portion thereof could match any of several substrings of
239 returns 0 for success and the non-zero code REG_NOMATCH for failure.
240 Other non-zero error codes may be returned in exceptional situations;
243 If REG_NOSUB was specified in the compilation of the RE,
250 argument (but see below for the case where REG_STARTEND is specified).
253 points to an array of
257 Such a structure has at least the members
263 (a signed arithmetic type at least as large as an
267 containing respectively the offset of the first character of a substring
268 and the offset of the first character after the end of the substring.
269 Offsets are measured from the beginning of the
273 An empty substring is denoted by equal offsets,
274 both indicating the character following the empty substring.
276 The 0th member of the
278 array is filled in to indicate what substring of
280 was matched by the entire RE.
281 Remaining members report what substring was matched by parenthesized
282 subexpressions within the RE;
285 reports subexpression
287 with subexpressions counted (starting at 1) by the order of their opening
288 parentheses in the RE, left to right.
289 Unused entries in the array\(emcorresponding either to subexpressions that
290 did not participate in the match at all, or to subexpressions that do not
291 exist in the RE (that is, \fIi\fR\ > \fIpreg\fR\->\fIre_nsub\fR)\(emhave both
296 If a subexpression participated in the match several times,
297 the reported substring is the last one it matched.
298 (Note, as an example in particular, that when the RE `(b*)+' matches `bbb',
299 the parenthesized subexpression matches each of the three `b's and then
300 an infinite number of empty strings following the last `b',
301 so the reported substring is one of the empties.)
303 If REG_STARTEND is specified,
305 must point to at least one
309 is 0 or REG_NOSUB was specified),
310 to hold the input offsets for REG_STARTEND.
311 Use for output is still entirely controlled by
315 is 0 or REG_NOSUB was specified,
318 will not be changed by a successful
328 to a human-readable, printable message.
332 the error code should have arisen from use of
337 and if the error code came from
339 it should have been the result from the most recent
344 may be able to supply a more detailed message using information
348 places the NUL-terminated message into the buffer pointed to by
350 limiting the length (including the NUL) to at most
353 If the whole message won't fit,
354 as much of it as will fit before the terminating NUL is supplied.
356 the returned value is the size of buffer needed to hold the whole
357 message (including terminating NUL).
362 is ignored but the return value is still correct.
368 is first ORed with REG_ITOA,
369 the ``message'' that results is the printable name of the error code,
370 e.g. ``REG_NOMATCH'',
371 rather than an explanation thereof.
377 shall be non-NULL and the
379 member of the structure it points to
380 must point to the printable name of an error code;
381 in this case, the result in
383 is the decimal digits of
384 the numeric value of the error code
385 (0 if the name is not recognized).
386 REG_ITOA and REG_ATOI are intended primarily as debugging facilities;
388 compatible with but not specified by POSIX 1003.2,
389 and should be used with
390 caution in software intended to be portable to other systems.
391 Be warned also that they are considered experimental and changes are possible.
394 frees any dynamically-allocated storage associated with the compiled RE
399 is no longer a valid compiled RE
400 and the effect of supplying it to
406 None of these functions references global variables except for tables
408 all are safe for use from multiple threads if the arguments are safe.
409 .SH IMPLEMENTATION CHOICES
410 There are a number of decisions that 1003.2 leaves up to the implementor,
411 either by explicitly saying ``undefined'' or by virtue of them being
412 forbidden by the RE grammar.
413 This implementation treats them as follows.
417 for a discussion of the definition of case-independent matching.
419 There is no particular limit on the length of REs,
420 except insofar as memory is limited.
421 Memory usage is approximately linear in RE size, and largely insensitive
422 to RE complexity, except for bounded repetitions.
423 See BUGS for one short RE using them
424 that will run almost any system out of memory.
426 A backslashed character other than one specifically given a magic meaning
427 by 1003.2 (such magic meanings occur only in obsolete [``basic''] REs)
428 is taken as an ordinary character.
430 Any unmatched [ is a REG_EBRACK error.
432 Equivalence classes cannot begin or end bracket-expression ranges.
433 The endpoint of one range cannot begin another.
435 RE_DUP_MAX, the limit on repetition counts in bounded repetitions, is 255.
437 A repetition operator (?, *, +, or bounds) cannot follow another
439 A repetition operator cannot begin an expression or subexpression
440 or follow `^' or `|'.
442 `|' cannot appear first or last in a (sub)expression or after another `|',
443 i.e. an operand of `|' cannot be an empty subexpression.
444 An empty parenthesized subexpression, `()', is legal and matches an
446 An empty string is not a legal RE.
448 A `{' followed by a digit is considered the beginning of bounds for a
449 bounded repetition, which must then follow the syntax for bounds.
450 A `{' \fInot\fR followed by a digit is considered an ordinary character.
452 `^' and `$' beginning and ending subexpressions in obsolete (``basic'')
453 REs are anchors, not ordinary characters.
455 grep(1), re_format(7)
457 POSIX 1003.2, sections 2.8 (Regular Expression Notation)
459 B.5 (C Binding for Regular Expression Matching).
461 Non-zero error codes from
465 include the following:
468 .ta \w'REG_ECOLLATE'u+3n
469 REG_NOMATCH regexec() failed to match
470 REG_BADPAT invalid regular expression
471 REG_ECOLLATE invalid collating element
472 REG_ECTYPE invalid character class
473 REG_EESCAPE \e applied to unescapable character
474 REG_ESUBREG invalid backreference number
475 REG_EBRACK brackets [ ] not balanced
476 REG_EPAREN parentheses ( ) not balanced
477 REG_EBRACE braces { } not balanced
478 REG_BADBR invalid repetition count(s) in { }
479 REG_ERANGE invalid character range in [ ]
480 REG_ESPACE ran out of memory
481 REG_BADRPT ?, *, or + operand invalid
482 REG_EMPTY empty (sub)expression
483 REG_ASSERT ``can't happen''\(emyou found a bug
484 REG_INVARG invalid argument, e.g. negative-length string
487 Originally written by Henry Spencer at University of Toronto.
488 Altered for inclusion in the 4.4BSD distribution.
490 This is an alpha release with known defects.
491 Please report problems.
493 There is one known functionality bug.
494 The implementation of internationalization is incomplete:
495 the locale is always assumed to be the default one of 1003.2,
496 and only the collating elements etc. of that locale are available.
498 The back-reference code is subtle and doubts linger about its correctness
503 This will improve with later releases.
505 exceeding 0 is expensive;
507 exceeding 1 is worse.
509 is largely insensitive to RE complexity \fIexcept\fR that back
510 references are massively expensive.
511 RE length does matter; in particular, there is a strong speed bonus
512 for keeping RE length under about 30 characters,
513 with most special characters counting roughly double.
516 implements bounded repetitions by macro expansion,
517 which is costly in time and space if counts are large
518 or bounded repetitions are nested.
520 `((((a{1,100}){1,100}){1,100}){1,100}){1,100}'
521 will (eventually) run almost any existing machine out of swap space.
523 There are suspected problems with response to obscure error conditions.
525 certain kinds of internal overflow,
526 produced only by truly enormous REs or by multiply nested bounded repetitions,
527 are probably not handled well.
529 Due to a mistake in 1003.2, things like `a)b' are legal REs because `)' is
530 a special character only in the presence of a previous unmatched `('.
531 This can't be fixed until the spec is fixed.
533 The standard's definition of back references is vague.
535 `a\e(\e(b\e)*\e2\e)*d' match `abbbd'?
536 Until the standard is clarified,
537 behavior in such cases should not be relied on.
539 The implementation of word-boundary matching is a bit of a kludge,
540 and bugs may lurk in combinations of word-boundary matching and anchoring.
projects / dragonfly.git / blob