]> git.ipfire.org Git - thirdparty/man-pages.git/blame - man7/regex.7
ld.so.8: tstamp
[thirdparty/man-pages.git] / man7 / regex.7
CommitLineData
fea681da
MK
1.\" From Henry Spencer's regex package (as found in the apache
2.\" distribution). The package carries the following copyright:
3.\"
4.\" Copyright 1992, 1993, 1994 Henry Spencer. All rights reserved.
5.\" This software is not subject to any license of the American Telephone
6.\" and Telegraph Company or of the Regents of the University of California.
c13182ef 7.\"
fea681da
MK
8.\" Permission is granted to anyone to use this software for any purpose
9.\" on any computer system, and to alter it and redistribute it, subject
10.\" to the following restrictions:
c13182ef 11.\"
fea681da
MK
12.\" 1. The author is not responsible for the consequences of use of this
13.\" software, no matter how awful, even if they arise from flaws in it.
c13182ef 14.\"
fea681da
MK
15.\" 2. The origin of this software must not be misrepresented, either by
16.\" explicit claim or by omission. Since few users ever read sources,
17.\" credits must appear in the documentation.
c13182ef 18.\"
fea681da
MK
19.\" 3. Altered versions must be plainly marked as such, and must not be
20.\" misrepresented as being the original software. Since few users
21.\" ever read sources, credits must appear in the documentation.
c13182ef 22.\"
fea681da 23.\" 4. This notice may not be removed or altered.
c13182ef 24.\"
fea681da
MK
25.\" In order to comply with `credits must appear in the documentation'
26.\" I added an AUTHOR paragraph below - aeb.
27.\"
28.\" In the default nroff environment there is no dagger \(dg.
bf6c69c9
MK
29.\"
30.\" 2005-05-11 Removed discussion of `[[:<:]]' and `[[:>:]]', which
31.\" appear not to be in the glibc implementation of regcomp
32.\"
fea681da
MK
33.ie t .ds dg \(dg
34.el .ds dg (!)
5a25ff94 35.TH REGEX 7 2007-12-12 "" "Linux Programmer's Manual"
fea681da 36.SH NAME
4dec66f9 37regex \- POSIX.2 regular expressions
fea681da 38.SH DESCRIPTION
324633ae 39Regular expressions ("RE"s),
4dec66f9 40as defined in POSIX.2, come in two forms:
fea681da
MK
41modern REs (roughly those of
42.IR egrep ;
324633ae 43POSIX.2 calls these "extended" REs)
fea681da
MK
44and obsolete REs (roughly those of
45.BR ed (1);
324633ae 46POSIX.2 "basic" REs).
fea681da
MK
47Obsolete REs mostly exist for backward compatibility in some old programs;
48they will be discussed at the end.
fa203d85 49POSIX.2 leaves some aspects of RE syntax and semantics open;
333a424b 50"\*(dg" marks decisions on these aspects that
fa203d85 51may not be fully portable to other POSIX.2 implementations.
fea681da 52.PP
1f04cc97 53A (modern) RE is one\*(dg or more non-empty\*(dg \fIbranches\fR,
333a424b 54separated by \(aq|\(aq.
fea681da
MK
55It matches anything that matches one of the branches.
56.PP
57A branch is one\*(dg or more \fIpieces\fR, concatenated.
58It matches a match for the first, followed by a match for the second, etc.
59.PP
60A piece is an \fIatom\fR possibly followed
333a424b 61by a single\*(dg \(aq*\(aq, \(aq+\(aq, \(aq?\(aq, or \fIbound\fR.
c45660d7
MK
62An atom followed by \(aq*\(aq
63matches a sequence of 0 or more matches of the atom.
64An atom followed by \(aq+\(aq
65matches a sequence of 1 or more matches of the atom.
66An atom followed by \(aq?\(aq
67matches a sequence of 0 or 1 matches of the atom.
fea681da 68.PP
333a424b
MK
69A \fIbound\fR is \(aq{\(aq followed by an unsigned decimal integer,
70possibly followed by \(aq,\(aq
fea681da 71possibly followed by another unsigned decimal integer,
333a424b 72always followed by \(aq}\(aq.
097585ed
MK
73The integers must lie between 0 and
74.B RE_DUP_MAX
75(255\*(dg) inclusive,
fea681da
MK
76and if there are two of them, the first may not exceed the second.
77An atom followed by a bound containing one integer \fIi\fR
78and no comma matches
79a sequence of exactly \fIi\fR matches of the atom.
80An atom followed by a bound
81containing one integer \fIi\fR and a comma matches
82a sequence of \fIi\fR or more matches of the atom.
83An atom followed by a bound
84containing two integers \fIi\fR and \fIj\fR matches
85a sequence of \fIi\fR through \fIj\fR (inclusive) matches of the atom.
86.PP
c45660d7
MK
87An atom is a regular expression enclosed in "\fI()\fP"
88(matching a match for the regular expression),
333a424b
MK
89an empty set of "\fI()\fP" (matching the null string)\*(dg,
90a \fIbracket expression\fR (see below), \(aq.\(aq
91(matching any single character), \(aq^\(aq (matching the null string at the
92beginning of a line), \(aq$\(aq (matching the null string at the
93end of a line), a \(aq\e\(aq followed by one of the characters
94"\fI^.[$()|*+?{\e\fP"
fea681da 95(matching that character taken as an ordinary character),
333a424b 96a \(aq\e\(aq followed by any other character\*(dg
fea681da 97(matching that character taken as an ordinary character,
333a424b 98as if the \(aq\e\(aq had not been present\*(dg),
fea681da 99or a single character with no other significance (matching that character).
333a424b 100A \(aq{\(aq followed by a character other than a digit is an ordinary
fea681da 101character, not the beginning of a bound\*(dg.
333a424b 102It is illegal to end an RE with \(aq\e\(aq.
fea681da 103.PP
333a424b 104A \fIbracket expression\fR is a list of characters enclosed in "\fI[]\fP".
fea681da 105It normally matches any single character from the list (but see below).
333a424b 106If the list begins with \(aq^\(aq,
fea681da
MK
107it matches any single character
108(but see below) \fInot\fR from the rest of the list.
333a424b 109If two characters in the list are separated by \(aq\-\(aq, this is shorthand
fea681da
MK
110for the full \fIrange\fR of characters between those two (inclusive) in the
111collating sequence,
333a424b 112for example, "\fI[0\-9]\fP" in ASCII matches any decimal digit.
fea681da 113It is illegal\*(dg for two ranges to share an
333a424b 114endpoint, for example, "\fIa-c-e\fP".
fea681da
MK
115Ranges are very collating-sequence-dependent,
116and portable programs should avoid relying on them.
117.PP
333a424b
MK
118To include a literal \(aq]\(aq in the list, make it the first character
119(following a possible \(aq^\(aq).
120To include a literal \(aq\-\(aq, make it the first or last character,
fea681da 121or the second endpoint of a range.
333a424b 122To use a literal \(aq\-\(aq as the first endpoint of a range,
c45660d7
MK
123enclose it in "\fI[.\fP" and "\fI.]\fP"
124to make it a collating element (see below).
333a424b
MK
125With the exception of these and some combinations using \(aq[\(aq (see next
126paragraphs), all other special characters, including \(aq\e\(aq, lose their
fea681da
MK
127special significance within a bracket expression.
128.PP
129Within a bracket expression, a collating element (a character,
130a multi-character sequence that collates as if it were a single character,
131or a collating-sequence name for either)
333a424b 132enclosed in "\fI[.\fP" and "\fI.]\fP" stands for the
fea681da
MK
133sequence of characters of that collating element.
134The sequence is a single element of the bracket expression's list.
c13182ef 135A bracket expression containing a multi-character collating element
fea681da 136can thus match more than one character,
333a424b
MK
137for example, if the collating sequence includes a "ch" collating element,
138then the RE "\fI[[.ch.]]*c\fP" matches the first five characters
139of "chchcc".
fea681da 140.PP
333a424b
MK
141Within a bracket expression, a collating element enclosed in "\fI[=\fP" and
142"\fI=]\fP" is an equivalence class, standing for the sequences of characters
fea681da
MK
143of all collating elements equivalent to that one, including itself.
144(If there are no other equivalent collating elements,
c45660d7
MK
145the treatment is as if the enclosing delimiters
146were "\fI[.\fP" and "\fI.]\fP".)
fea681da 147For example, if o and \o'o^' are the members of an equivalence class,
c45660d7
MK
148then "\fI[[=o=]]\fP", "\fI[[=\o'o^'=]]\fP",
149and "\fI[o\o'o^']\fP" are all synonymous.
fea681da
MK
150An equivalence class may not\*(dg be an endpoint
151of a range.
152.PP
153Within a bracket expression, the name of a \fIcharacter class\fR enclosed
c45660d7
MK
154in "\fI[:\fP" and "\fI:]\fP" stands for the list
155of all characters belonging to that
fea681da
MK
156class.
157Standard character class names are:
158.PP
159.RS
160.nf
161.ta 3c 6c 9c
162alnum digit punct
163alpha graph space
164blank lower upper
165cntrl print xdigit
166.fi
167.RE
168.PP
169These stand for the character classes defined in
170.BR wctype (3).
171A locale may provide others.
172A character class may not be used as an endpoint of a range.
bf6c69c9
MK
173.\" As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=295666
174.\" The following does not seem to apply in the glibc implementation
175.\" .PP
176.\" There are two special cases\*(dg of bracket expressions:
c45660d7
MK
177.\" the bracket expressions "\fI[[:<:]]\fP" and "\fI[[:>:]]\fP" match
178.\" the null string at the beginning and end of a word respectively.
bf6c69c9
MK
179.\" A word is defined as a sequence of
180.\" word characters
181.\" which is neither preceded nor followed by
182.\" word characters.
183.\" A word character is an
184.\" .I alnum
185.\" character (as defined by
186.\" .BR wctype (3))
187.\" or an underscore.
188.\" This is an extension,
4dec66f9 189.\" compatible with but not specified by POSIX.2,
bf6c69c9
MK
190.\" and should be used with
191.\" caution in software intended to be portable to other systems.
fea681da
MK
192.PP
193In the event that an RE could match more than one substring of a given
194string,
195the RE matches the one starting earliest in the string.
196If the RE could match more than one substring starting at that point,
197it matches the longest.
198Subexpressions also match the longest possible substrings, subject to
199the constraint that the whole match be as long as possible,
200with subexpressions starting earlier in the RE taking priority over
201ones starting later.
202Note that higher-level subexpressions thus take priority over
203their lower-level component subexpressions.
204.PP
205Match lengths are measured in characters, not collating elements.
206A null string is considered longer than no match at all.
207For example,
333a424b 208"\fIbb*\fP" matches the three middle characters of "abbbc",
c45660d7
MK
209"\fI(wee|week)(knights|nights)\fP"
210matches all ten characters of "weeknights",
333a424b 211when "\fI(.*).*\fP" is matched against "abc" the parenthesized subexpression
fea681da 212matches all three characters, and
c45660d7
MK
213when "\fI(a*)*\fP" is matched against "bc"
214both the whole RE and the parenthesized
fea681da
MK
215subexpression match the null string.
216.PP
217If case-independent matching is specified,
218the effect is much as if all case distinctions had vanished from the
219alphabet.
220When an alphabetic that exists in multiple cases appears as an
221ordinary character outside a bracket expression, it is effectively
222transformed into a bracket expression containing both cases,
333a424b 223for example, \(aqx\(aq becomes "\fI[xX]\fP".
fea681da 224When it appears inside a bracket expression, all case counterparts
333a424b
MK
225of it are added to the bracket expression, so that, for example, "\fI[x]\fP"
226becomes "\fI[xX]\fP" and "\fI[^x]\fP" becomes "\fI[^xX]\fP".
fea681da
MK
227.PP
228No particular limit is imposed on the length of REs\*(dg.
229Programs intended to be portable should not employ REs longer
230than 256 bytes,
231as an implementation can refuse to accept such REs and remain
232POSIX-compliant.
233.PP
324633ae 234Obsolete ("basic") regular expressions differ in several respects.
c45660d7
MK
235\(aq|\(aq, \(aq+\(aq, and \(aq?\(aq are
236ordinary characters and there is no equivalent
fea681da 237for their functionality.
333a424b
MK
238The delimiters for bounds are "\fI\e{\fP" and "\fI\e}\fP",
239with \(aq{\(aq and \(aq}\(aq by themselves ordinary characters.
240The parentheses for nested subexpressions are "\fI\e(\fP" and "\fI\e)\fP",
241with \(aq(\(aq and \(aq)\(aq by themselves ordinary characters.
242\(aq^\(aq is an ordinary character except at the beginning of the
fea681da 243RE or\*(dg the beginning of a parenthesized subexpression,
333a424b 244\(aq$\(aq is an ordinary character except at the end of the
fea681da 245RE or\*(dg the end of a parenthesized subexpression,
333a424b 246and \(aq*\(aq is an ordinary character if it appears at the beginning of the
fea681da 247RE or the beginning of a parenthesized subexpression
333a424b 248(after a possible leading \(aq^\(aq).
4f020e78 249.PP
fea681da 250Finally, there is one new type of atom, a \fIback reference\fR:
333a424b 251\(aq\e\(aq followed by a non-zero decimal digit \fId\fR
fea681da
MK
252matches the same sequence of characters
253matched by the \fId\fRth parenthesized subexpression
254(numbering subexpressions by the positions of their opening parentheses,
255left to right),
333a424b 256so that, for example, "\fI\e([bc]\e)\e1\fP" matches "bb" or "cc" but not "bc".
fea681da
MK
257.SH BUGS
258Having two kinds of REs is a botch.
259.PP
333a424b
MK
260The current POSIX.2 spec says that \(aq)\(aq is an ordinary character in
261the absence of an unmatched \(aq(\(aq;
fea681da
MK
262this was an unintentional result of a wording error,
263and change is likely.
264Avoid relying on it.
265.PP
266Back references are a dreadful botch,
267posing major problems for efficient implementations.
268They are also somewhat vaguely defined
269(does
333a424b 270"\fIa\e(\e(b\e)*\e2\e)*d\fP" match "abbbd"?).
fea681da
MK
271Avoid using them.
272.PP
fa203d85 273POSIX.2's specification of case-independent matching is vague.
324633ae 274The "one case implies all cases" definition given above
fea681da 275is current consensus among implementors as to the right interpretation.
4f020e78
MK
276.\" As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=295666
277.\" The following does not seem to apply in the glibc implementation
278.\" .PP
279.\" The syntax for word boundaries is incredibly ugly.
fd7f0a7f
MK
280.\" .SH AUTHOR
281.\" This page was taken from Henry Spencer's regex package.
e37e3282 282.SH "SEE ALSO"
845d36d6 283.BR grep (1),
e37e3282
MK
284.BR regex (3)
285.PP
286POSIX.2, section 2.8 (Regular Expression Notation).