Debian Codegraph @

upstream/debian-unstable/man7/regex.7

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