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 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" @(#)regex.3 8.4 (Berkeley) 3/20/94
33 .\" $FreeBSD: src/lib/libc/regex/regex.3,v 1.21 2007/01/09 00:28:04 imp Exp $
34 .\" $DragonFly: src/lib/libc/regex/regex.3,v 1.5 2008/06/02 06:50:08 hasso Exp $
44 .Nd regular-expression library
51 .Fa "regex_t * restrict preg" "const char * restrict pattern" "int cflags"
55 .Fa "const regex_t * restrict preg" "const char * restrict string"
56 .Fa "size_t nmatch" "regmatch_t pmatch[restrict]" "int eflags"
60 .Fa "int errcode" "const regex_t * restrict preg"
61 .Fa "char * restrict errbuf" "size_t errbuf_size"
64 .Fn regfree "regex_t *preg"
66 These routines implement
75 compiles an RE written as a string into an internal form,
77 matches that internal form against a string and reports results,
79 transforms error codes from either into human-readable messages,
82 frees any dynamically-allocated storage used by the internal form
87 declares two structure types,
91 the former for compiled internal forms and the latter for match reporting.
92 It also declares the four functions,
95 and a number of constants with names starting with
101 compiles the regular expression contained in the
104 subject to the flags in
106 and places the results in the
108 structure pointed to by
113 is the bitwise OR of zero or more of the following flags:
114 .Bl -tag -width REG_EXTENDED
119 rather than the obsolete
124 This is a synonym for 0,
125 provided as a counterpart to
127 to improve readability.
129 Compile with recognition of all special characters turned off.
130 All characters are thus considered ordinary,
134 This is an extension,
135 compatible with but not specified by
137 and should be used with
138 caution in software intended to be portable to other systems.
146 Compile for matching that ignores upper/lower case distinctions.
150 Compile for matching that need only report success or failure,
151 not what was matched.
153 Compile for newline-sensitive matching.
154 By default, newline is a completely ordinary character with no special
155 meaning in either REs or strings.
158 bracket expressions and
163 anchor matches the null string after any newline in the string
164 in addition to its normal function,
167 anchor matches the null string before any newline in the
168 string in addition to its normal function.
170 The regular expression ends,
171 not at the first NUL,
172 but just before the character pointed to by the
174 member of the structure pointed to by
180 This flag permits inclusion of NULs in the RE;
181 they are considered ordinary characters.
182 This is an extension,
183 compatible with but not specified by
185 and should be used with
186 caution in software intended to be portable to other systems.
191 returns 0 and fills in the structure pointed to by
193 One member of that structure
200 contains the number of parenthesized subexpressions within the RE
201 (except that the value of this member is undefined if the
206 fails, it returns a non-zero error code;
213 matches the compiled RE pointed to by
217 subject to the flags in
219 and reports results using
222 and the returned value.
223 The RE must have been compiled by a previous invocation of
225 The compiled form is not altered during execution of
227 so a single compiled RE can be used simultaneously by multiple threads.
230 the NUL-terminated string pointed to by
232 is considered to be the text of an entire line, minus any terminating
236 argument is the bitwise OR of zero or more of the following flags:
237 .Bl -tag -width REG_STARTEND
239 The first character of
241 is not the beginning of a line, so the
243 anchor should not match before it.
244 This does not affect the behavior of newlines under
249 does not end a line, so the
251 anchor should not match before it.
252 This does not affect the behavior of newlines under
255 The string is considered to start at
258 .Fa pmatch Ns [0]. Ns Va rm_so
259 and to have a terminating NUL located at
262 .Fa pmatch Ns [0]. Ns Va rm_eo
263 (there need not actually be a NUL at that location),
264 regardless of the value of
266 See below for the definition of
270 This is an extension,
271 compatible with but not specified by
273 and should be used with
274 caution in software intended to be portable to other systems.
280 affects only the location of the string,
281 not how it is matched.
286 for a discussion of what is matched in situations where an RE or a
287 portion thereof could match any of several substrings of
292 returns 0 for success and the non-zero code
295 Other non-zero error codes may be returned in exceptional situations;
301 was specified in the compilation of the RE,
308 argument (but see below for the case where
313 points to an array of
317 Such a structure has at least the members
323 (a signed arithmetic type at least as large as an
327 containing respectively the offset of the first character of a substring
328 and the offset of the first character after the end of the substring.
329 Offsets are measured from the beginning of the
333 An empty substring is denoted by equal offsets,
334 both indicating the character following the empty substring.
336 The 0th member of the
338 array is filled in to indicate what substring of
340 was matched by the entire RE.
341 Remaining members report what substring was matched by parenthesized
342 subexpressions within the RE;
345 reports subexpression
347 with subexpressions counted (starting at 1) by the order of their opening
348 parentheses in the RE, left to right.
349 Unused entries in the array (corresponding either to subexpressions that
350 did not participate in the match at all, or to subexpressions that do not
351 exist in the RE (that is,
354 .Fa preg Ns -> Ns Va re_nsub ) )
360 If a subexpression participated in the match several times,
361 the reported substring is the last one it matched.
362 (Note, as an example in particular, that when the RE
366 the parenthesized subexpression matches each of the three
369 an infinite number of empty strings following the last
371 so the reported substring is one of the empties.)
377 must point to at least one
384 to hold the input offsets for
386 Use for output is still entirely controlled by
395 will not be changed by a successful
407 to a human-readable, printable message.
411 .No non\- Ns Dv NULL ,
412 the error code should have arisen from use of
417 and if the error code came from
419 it should have been the result from the most recent
425 may be able to supply a more detailed message using information
431 places the NUL-terminated message into the buffer pointed to by
433 limiting the length (including the NUL) to at most
436 If the whole message will not fit,
437 as much of it as will fit before the terminating NUL is supplied.
439 the returned value is the size of buffer needed to hold the whole
440 message (including terminating NUL).
445 is ignored but the return value is still correct.
455 that results is the printable name of the error code,
458 rather than an explanation thereof.
469 member of the structure it points to
470 must point to the printable name of an error code;
471 in this case, the result in
473 is the decimal digits of
474 the numeric value of the error code
475 (0 if the name is not recognized).
479 are intended primarily as debugging facilities;
481 compatible with but not specified by
483 and should be used with
484 caution in software intended to be portable to other systems.
485 Be warned also that they are considered experimental and changes are possible.
490 frees any dynamically-allocated storage associated with the compiled RE
495 is no longer a valid compiled RE
496 and the effect of supplying it to
502 None of these functions references global variables except for tables
504 all are safe for use from multiple threads if the arguments are safe.
505 .Sh IMPLEMENTATION CHOICES
506 There are a number of decisions that
508 leaves up to the implementor,
509 either by explicitly saying
511 or by virtue of them being
512 forbidden by the RE grammar.
513 This implementation treats them as follows.
517 for a discussion of the definition of case-independent matching.
519 There is no particular limit on the length of REs,
520 except insofar as memory is limited.
521 Memory usage is approximately linear in RE size, and largely insensitive
522 to RE complexity, except for bounded repetitions.
525 for one short RE using them
526 that will run almost any system out of memory.
528 A backslashed character other than one specifically given a magic meaning
531 (such magic meanings occur only in obsolete
534 is taken as an ordinary character.
542 Equivalence classes cannot begin or end bracket-expression ranges.
543 The endpoint of one range cannot begin another.
546 the limit on repetition counts in bounded repetitions, is 255.
548 A repetition operator
553 cannot follow another
555 A repetition operator cannot begin an expression or subexpression
562 cannot appear first or last in a (sub)expression or after another
566 cannot be an empty subexpression.
567 An empty parenthesized subexpression,
569 is legal and matches an
571 An empty string is not a legal RE.
575 followed by a digit is considered the beginning of bounds for a
576 bounded repetition, which must then follow the syntax for bounds.
580 followed by a digit is considered an ordinary character.
585 beginning and ending subexpressions in obsolete
587 REs are anchors, not ordinary characters.
589 Non-zero error codes from
593 include the following:
595 .Bl -tag -width REG_ECOLLATE -compact
602 invalid regular expression
604 invalid collating element
606 invalid character class
609 applied to unescapable character
611 invalid backreference number
625 invalid repetition count(s) in
628 invalid character range in
639 empty (sub)expression
641 cannot happen - you found a bug
643 invalid argument, e.g.\& negative-length string
645 illegal byte sequence (bad multibyte character)
652 sections 2.8 (Regular Expression Notation)
654 B.5 (C Binding for Regular Expression Matching).
656 Originally written by
658 Altered for inclusion in the
662 This is an alpha release with known defects.
663 Please report problems.
665 The back-reference code is subtle and doubts linger about its correctness
672 This will improve with later releases.
676 exceeding 0 is expensive;
678 exceeding 1 is worse.
682 is largely insensitive to RE complexity
685 references are massively expensive.
686 RE length does matter; in particular, there is a strong speed bonus
687 for keeping RE length under about 30 characters,
688 with most special characters counting roughly double.
693 implements bounded repetitions by macro expansion,
694 which is costly in time and space if counts are large
695 or bounded repetitions are nested.
697 .Ql "((((a{1,100}){1,100}){1,100}){1,100}){1,100}"
698 will (eventually) run almost any existing machine out of swap space.
700 There are suspected problems with response to obscure error conditions.
702 certain kinds of internal overflow,
703 produced only by truly enormous REs or by multiply nested bounded repetitions,
704 are probably not handled well.
710 are legal REs because
713 a special character only in the presence of a previous unmatched
715 This cannot be fixed until the spec is fixed.
717 The standard's definition of back references is vague.
719 .Ql "a\e(\e(b\e)*\e2\e)*d"
722 Until the standard is clarified,
723 behavior in such cases should not be relied on.
725 The implementation of word-boundary matching is a bit of a kludge,
726 and bugs may lurk in combinations of word-boundary matching and anchoring.
728 Word-boundary matching does not work properly in multibyte locales.