1 .\" Copyright (c) 1992, 1993, 1994 Henry Spencer.
2 .\" Copyright (c) 1992, 1993, 1994
3 .\" The Regents of the University of California. All rights reserved.
5 .\" This code is derived from software contributed to Berkeley by
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. All advertising materials mentioning features or use of this software
17 .\" must display the following acknowledgement:
18 .\" This product includes software developed by the University of
19 .\" California, Berkeley and its contributors.
20 .\" 4. Neither the name of the University nor the names of its contributors
21 .\" may be used to endorse or promote products derived from this software
22 .\" without specific prior written permission.
24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36 .\" @(#)regex.3 8.4 (Berkeley) 3/20/94
39 .TH REGEX 3 "March 20, 1994"
41 .\" one other place knows this name: the SEE ALSO section
42 .IR re_format (7) \\$1
45 regcomp, regexec, regerror, regfree \- regular-expression library
49 #include <sys/types.h>
53 int regcomp(regex_t\ *preg, const\ char\ *pattern, int\ cflags);
55 int\ regexec(const\ regex_t\ *preg, const\ char\ *string,
56 size_t\ nmatch, regmatch_t\ pmatch[], int\ eflags);
58 size_t\ regerror(int\ errcode, const\ regex_t\ *preg,
59 char\ *errbuf, size_t\ errbuf_size);
61 void\ regfree(regex_t\ *preg);
65 These routines implement POSIX 1003.2 regular expressions (``RE''s);
69 compiles an RE written as a string into an internal form,
71 matches that internal form against a string and reports results,
73 transforms error codes from either into human-readable messages,
76 frees any dynamically-allocated storage used by the internal form
81 declares two structure types,
85 the former for compiled internal forms and the latter for match reporting.
86 It also declares the four functions,
89 and a number of constants with names starting with ``REG_''.
92 compiles the regular expression contained in the
95 subject to the flags in
97 and places the results in the
99 structure pointed to by
102 is the bitwise OR of zero or more of the following flags:
103 .IP REG_EXTENDED \w'REG_EXTENDED'u+2n
104 Compile modern (``extended'') REs,
105 rather than the obsolete (``basic'') REs that
108 This is a synonym for 0,
109 provided as a counterpart to REG_EXTENDED to improve readability.
111 Compile with recognition of all special characters turned off.
112 All characters are thus considered ordinary,
113 so the ``RE'' is a literal string.
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 REG_EXTENDED and REG_NOSPEC may not be used
122 Compile for matching that ignores upper/lower case distinctions.
126 Compile for matching that need only report success or failure,
127 not what was matched.
129 Compile for newline-sensitive matching.
130 By default, newline is a completely ordinary character with no special
131 meaning in either REs or strings.
133 `[^' bracket expressions and `.' never match newline,
134 a `^' anchor matches the null string after any newline in the string
135 in addition to its normal function,
136 and the `$' anchor matches the null string before any newline in the
137 string in addition to its normal function.
139 The regular expression ends,
140 not at the first NUL,
141 but just before the character pointed to by the
143 member of the structure pointed to by
149 This flag permits inclusion of NULs in the RE;
150 they are considered ordinary characters.
151 This is an extension,
152 compatible with but not specified by POSIX 1003.2,
153 and should be used with
154 caution in software intended to be portable to other systems.
158 returns 0 and fills in the structure pointed to by
160 One member of that structure
167 contains the number of parenthesized subexpressions within the RE
168 (except that the value of this member is undefined if the
169 REG_NOSUB flag was used).
172 fails, it returns a non-zero error code;
176 matches the compiled RE pointed to by
180 subject to the flags in
182 and reports results using
185 and the returned value.
186 The RE must have been compiled by a previous invocation of
188 The compiled form is not altered during execution of
190 so a single compiled RE can be used simultaneously by multiple threads.
193 the NUL-terminated string pointed to by
195 is considered to be the text of an entire line, minus any terminating
199 argument is the bitwise OR of zero or more of the following flags:
200 .IP REG_NOTBOL \w'REG_STARTEND'u+2n
201 The first character of
203 is not the beginning of a line, so the `^' anchor should not match before it.
204 This does not affect the behavior of newlines under REG_NEWLINE.
208 does not end a line, so the `$' anchor should not match before it.
209 This does not affect the behavior of newlines under REG_NEWLINE.
211 The string is considered to start at
212 \fIstring\fR\ + \fIpmatch\fR[0].\fIrm_so\fR
213 and to have a terminating NUL located at
214 \fIstring\fR\ + \fIpmatch\fR[0].\fIrm_eo\fR
215 (there need not actually be a NUL at that location),
216 regardless of the value of
218 See below for the definition of
222 This is an extension,
223 compatible with but not specified by POSIX 1003.2,
224 and should be used with
225 caution in software intended to be portable to other systems.
226 Note that a non-zero \fIrm_so\fR does not imply REG_NOTBOL;
227 REG_STARTEND affects only the location of the string,
228 not how it is matched.
232 for a discussion of what is matched in situations where an RE or a
233 portion thereof could match any of several substrings of
238 returns 0 for success and the non-zero code REG_NOMATCH for failure.
239 Other non-zero error codes may be returned in exceptional situations;
242 If REG_NOSUB was specified in the compilation of the RE,
249 argument (but see below for the case where REG_STARTEND is specified).
252 points to an array of
256 Such a structure has at least the members
262 (a signed arithmetic type at least as large as an
266 containing respectively the offset of the first character of a substring
267 and the offset of the first character after the end of the substring.
268 Offsets are measured from the beginning of the
272 An empty substring is denoted by equal offsets,
273 both indicating the character following the empty substring.
275 The 0th member of the
277 array is filled in to indicate what substring of
279 was matched by the entire RE.
280 Remaining members report what substring was matched by parenthesized
281 subexpressions within the RE;
284 reports subexpression
286 with subexpressions counted (starting at 1) by the order of their opening
287 parentheses in the RE, left to right.
288 Unused entries in the array\(emcorresponding either to subexpressions that
289 did not participate in the match at all, or to subexpressions that do not
290 exist in the RE (that is, \fIi\fR\ > \fIpreg\fR\->\fIre_nsub\fR)\(emhave both
295 If a subexpression participated in the match several times,
296 the reported substring is the last one it matched.
297 (Note, as an example in particular, that when the RE `(b*)+' matches `bbb',
298 the parenthesized subexpression matches each of the three `b's and then
299 an infinite number of empty strings following the last `b',
300 so the reported substring is one of the empties.)
302 If REG_STARTEND is specified,
304 must point to at least one
308 is 0 or REG_NOSUB was specified),
309 to hold the input offsets for REG_STARTEND.
310 Use for output is still entirely controlled by
314 is 0 or REG_NOSUB was specified,
317 will not be changed by a successful
327 to a human-readable, printable message.
331 the error code should have arisen from use of
336 and if the error code came from
338 it should have been the result from the most recent
343 may be able to supply a more detailed message using information
347 places the NUL-terminated message into the buffer pointed to by
349 limiting the length (including the NUL) to at most
352 If the whole message won't fit,
353 as much of it as will fit before the terminating NUL is supplied.
355 the returned value is the size of buffer needed to hold the whole
356 message (including terminating NUL).
361 is ignored but the return value is still correct.
367 is first ORed with REG_ITOA,
368 the ``message'' that results is the printable name of the error code,
369 e.g. ``REG_NOMATCH'',
370 rather than an explanation thereof.
376 shall be non-NULL and the
378 member of the structure it points to
379 must point to the printable name of an error code;
380 in this case, the result in
382 is the decimal digits of
383 the numeric value of the error code
384 (0 if the name is not recognized).
385 REG_ITOA and REG_ATOI are intended primarily as debugging facilities;
387 compatible with but not specified by POSIX 1003.2,
388 and should be used with
389 caution in software intended to be portable to other systems.
390 Be warned also that they are considered experimental and changes are possible.
393 frees any dynamically-allocated storage associated with the compiled RE
398 is no longer a valid compiled RE
399 and the effect of supplying it to
405 None of these functions references global variables except for tables
407 all are safe for use from multiple threads if the arguments are safe.
408 .SH IMPLEMENTATION CHOICES
409 There are a number of decisions that 1003.2 leaves up to the implementor,
410 either by explicitly saying ``undefined'' or by virtue of them being
411 forbidden by the RE grammar.
412 This implementation treats them as follows.
416 for a discussion of the definition of case-independent matching.
418 There is no particular limit on the length of REs,
419 except insofar as memory is limited.
420 Memory usage is approximately linear in RE size, and largely insensitive
421 to RE complexity, except for bounded repetitions.
422 See BUGS for one short RE using them
423 that will run almost any system out of memory.
425 A backslashed character other than one specifically given a magic meaning
426 by 1003.2 (such magic meanings occur only in obsolete [``basic''] REs)
427 is taken as an ordinary character.
429 Any unmatched [ is a REG_EBRACK error.
431 Equivalence classes cannot begin or end bracket-expression ranges.
432 The endpoint of one range cannot begin another.
434 RE_DUP_MAX, the limit on repetition counts in bounded repetitions, is 255.
436 A repetition operator (?, *, +, or bounds) cannot follow another
438 A repetition operator cannot begin an expression or subexpression
439 or follow `^' or `|'.
441 `|' cannot appear first or last in a (sub)expression or after another `|',
442 i.e. an operand of `|' cannot be an empty subexpression.
443 An empty parenthesized subexpression, `()', is legal and matches an
445 An empty string is not a legal RE.
447 A `{' followed by a digit is considered the beginning of bounds for a
448 bounded repetition, which must then follow the syntax for bounds.
449 A `{' \fInot\fR followed by a digit is considered an ordinary character.
451 `^' and `$' beginning and ending subexpressions in obsolete (``basic'')
452 REs are anchors, not ordinary characters.
454 grep(1), re_format(7)
456 POSIX 1003.2, sections 2.8 (Regular Expression Notation)
458 B.5 (C Binding for Regular Expression Matching).
460 Non-zero error codes from
464 include the following:
467 .ta \w'REG_ECOLLATE'u+3n
468 REG_NOMATCH regexec() failed to match
469 REG_BADPAT invalid regular expression
470 REG_ECOLLATE invalid collating element
471 REG_ECTYPE invalid character class
472 REG_EESCAPE \e applied to unescapable character
473 REG_ESUBREG invalid backreference number
474 REG_EBRACK brackets [ ] not balanced
475 REG_EPAREN parentheses ( ) not balanced
476 REG_EBRACE braces { } not balanced
477 REG_BADBR invalid repetition count(s) in { }
478 REG_ERANGE invalid character range in [ ]
479 REG_ESPACE ran out of memory
480 REG_BADRPT ?, *, or + operand invalid
481 REG_EMPTY empty (sub)expression
482 REG_ASSERT ``can't happen''\(emyou found a bug
483 REG_INVARG invalid argument, e.g. negative-length string
486 Originally written by Henry Spencer.
487 Altered for inclusion in the
491 This is an alpha release with known defects.
492 Please report problems.
494 There is one known functionality bug.
495 The implementation of internationalization is incomplete:
496 the locale is always assumed to be the default one of 1003.2,
497 and only the collating elements etc. of that locale are available.
499 The back-reference code is subtle and doubts linger about its correctness
504 This will improve with later releases.
506 exceeding 0 is expensive;
508 exceeding 1 is worse.
510 is largely insensitive to RE complexity \fIexcept\fR that back
511 references are massively expensive.
512 RE length does matter; in particular, there is a strong speed bonus
513 for keeping RE length under about 30 characters,
514 with most special characters counting roughly double.
517 implements bounded repetitions by macro expansion,
518 which is costly in time and space if counts are large
519 or bounded repetitions are nested.
521 `((((a{1,100}){1,100}){1,100}){1,100}){1,100}'
522 will (eventually) run almost any existing machine out of swap space.
524 There are suspected problems with response to obscure error conditions.
526 certain kinds of internal overflow,
527 produced only by truly enormous REs or by multiply nested bounded repetitions,
528 are probably not handled well.
530 Due to a mistake in 1003.2, things like `a)b' are legal REs because `)' is
531 a special character only in the presence of a previous unmatched `('.
532 This can't be fixed until the spec is fixed.
534 The standard's definition of back references is vague.
536 `a\e(\e(b\e)*\e2\e)*d' match `abbbd'?
537 Until the standard is clarified,
538 behavior in such cases should not be relied on.
540 The implementation of word-boundary matching is a bit of a kludge,
541 and bugs may lurk in combinations of word-boundary matching and anchoring.