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