Print this page
3768 fnmatch(5) is worded poorly
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man5/fnmatch.5
+++ new/usr/src/man/man5/fnmatch.5
1 1 '\" te
|
↓ open down ↓ |
1 lines elided |
↑ open up ↑ |
2 2 .\" Copyright (c) 1992, X/Open Company Limited
3 3 .\" All Rights Reserved Portions Copyright (c) 1995, Sun Microsystems, Inc.
4 4 .\" All Rights Reserved
5 5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
6 6 .\" http://www.opengroup.org/bookstore/.
7 7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
8 8 .\" This notice shall appear on any product containing this material.
9 9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
10 10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
11 11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
12 -.TH FNMATCH 5 "Mar 28, 1995"
12 +.TH FNMATCH 5 "Jun 14, 2015"
13 13 .SH NAME
14 14 fnmatch \- file name pattern matching
15 15 .SH DESCRIPTION
16 -.sp
17 16 .LP
18 17 The pattern matching notation described below is used to specify patterns for
19 18 matching strings in the shell. Historically, pattern matching notation is
20 19 related to, but slightly different from, the regular expression notation. For
21 20 this reason, the description of the rules for this pattern matching notation is
22 21 based on the description of regular expression notation described on the
23 22 \fBregex\fR(5) manual page.
24 23 .SS "Patterns Matching a Single Character"
25 -.sp
26 24 .LP
27 -The following \fIpatterns matching a single character\fR match a single
28 -character: \fIordinary characters\fR, \fIspecial pattern characters\fR and
29 -\fIpattern bracket expressions\fR. The pattern bracket expression will also
30 -match a single collating element.
25 +The following patterns match a single character: \fIordinary characters\fR,
26 +\fIspecial pattern characters\fR and \fIpattern bracket expressions\fR. The pattern
27 +bracket expression will also match a single collating element.
31 28 .sp
32 29 .LP
33 30 An ordinary character is a pattern that matches itself. It can be any character
34 31 in the supported character set except for \fINUL\fR, those special shell
35 32 characters that require quoting, and the following three special pattern
36 33 characters. Matching is based on the bit pattern used for encoding the
37 34 character, not on the graphic representation of the character. If any character
38 35 (ordinary, shell special, or pattern special) is quoted, that pattern will
39 36 match the character itself. The shell special characters always require
40 37 quoting.
41 38 .sp
42 39 .LP
43 40 When unquoted and outside a bracket expression, the following three characters
44 41 will have special meaning in the specification of patterns:
45 42 .sp
46 43 .ne 2
47 44 .na
48 45 \fB\fB?\fR \fR
49 46 .ad
50 47 .RS 6n
51 48 A question-mark is a pattern that will match any character.
52 49 .RE
53 50
54 51 .sp
55 52 .ne 2
56 53 .na
57 54 \fB\fB*\fR \fR
58 55 .ad
59 56 .RS 6n
60 57 An asterisk is a pattern that will match multiple characters, as described in
61 58 \fBPatterns Matching Multiple Characters\fR, below.
62 59 .RE
63 60
64 61 .sp
65 62 .ne 2
66 63 .na
67 64 \fB\fB[\fR \fR
68 65 .ad
69 66 .RS 6n
70 67 The open bracket will introduce a pattern bracket expression.
71 68 .RE
72 69
73 70 .sp
74 71 .LP
75 72 The description of basic regular expression bracket expressions on the
76 73 \fBregex\fR(5) manual page also applies to the pattern bracket expression,
77 74 except that the exclamation-mark character \fB(\fR \fB!\fR \fB)\fR replaces the
78 75 circumflex character (\fB^\fR) in its role in a \fInon-matching list\fR in the
79 76 regular expression notation. A bracket expression starting with an unquoted
80 77 circumflex character produces unspecified results.
81 78 .sp
82 79 .LP
83 80 The restriction on a circumflex in a bracket expression is to allow
84 81 implementations that support pattern matching using the circumflex as the
85 82 negation character in addition to the exclamation-mark. A portable application
86 83 must use something like \fB[\e^!\fR] to match either character.
87 84 .sp
88 85 .LP
89 86 When pattern matching is used where shell quote removal is not performed (such
90 87 as in the argument to the \fBfind\fR \fB-name\fR primary when \fBfind\fR is
91 88 being called using one of the \fBexec\fR functions, or in the \fIpattern\fR
92 89 argument to the \fBfnmatch\fR(3C) function, special characters can be escaped
93 90 to remove their special meaning by preceding them with a backslash character.
94 91 This escaping backslash will be discarded. The sequence \fB\e\e\fR represents
95 92 one literal backslash. All of the requirements and effects of quoting on
96 93 ordinary, shell special and special pattern characters will apply to escaping
97 94 in this context.
98 95 .sp
99 96 .LP
100 97 Both quoting and escaping are described here because pattern matching must work
101 98 in three separate circumstances:
102 99 .RS +4
103 100 .TP
104 101 .ie t \(bu
105 102 .el o
106 103 Calling directly upon the shell, such as in pathname expansion or in a
107 104 \fBcase\fR statement. All of the following will match the string or file
108 105 \fBabc\fR:
109 106 .sp
110 107
111 108 .sp
112 109 .TS
113 110 l l l l l
114 111 l l l l l .
115 112 \fBabc\fR \fB"abc"\fR \fBa"b"c\fR \fBa\ebc\fR \fBa[b]c\fR
116 113 \fBa["b"]c\fR \fBa[\eb]c\fR \fBa["\eb"]c\fR \fBa?c\fR \fBa*c\fR
117 114 .TE
118 115
119 116 The following will not:
120 117 .sp
121 118
122 119 .sp
123 120 .TS
124 121 l l l .
125 122 \fB"a?c"\fR \fBa\e*c\fR \fBa\e[b]c\fR
126 123 .TE
127 124
128 125 .RE
129 126 .RS +4
130 127 .TP
131 128 .ie t \(bu
132 129 .el o
133 130 Calling a utility or function without going through a shell, as described for
134 131 \fBfind\fR(1) and the function \fBfnmatch\fR(3C)
135 132 .RE
136 133 .RS +4
137 134 .TP
138 135 .ie t \(bu
139 136 .el o
140 137 Calling utilities such as \fBfind\fR, \fBcpio\fR, \fBtar\fR or \fBpax\fR
141 138 through the shell command line. In this case, shell quote removal is performed
142 139 before the utility sees the argument. For example, in:
143 140 .sp
144 141 find /bin -name e\ec[\eh]o -print
145 142 .sp
146 143 after quote removal, the backslashes are presented to \fBfind\fR and it treats
147 144 them as escape characters. Both precede ordinary characters, so the \fBc\fR and
148 145 \fBh\fR represent themselves and \fBecho\fR would be found on many historical
149 146 systems (that have it in \fB/bin\fR). To find a file name that contained shell
150 147 special characters or pattern characters, both quoting and escaping are
151 148 required, such as:
152 149 .sp
153 150 \fBpax -r .\|.\|. "*a\e\|(\|\e?"\fR
154 151 .sp
|
↓ open down ↓ |
114 lines elided |
↑ open up ↑ |
155 152 to extract a filename ending with \fBa(?\fR.
156 153 .RE
157 154 .sp
158 155 .LP
159 156 Conforming applications are required to quote or escape the shell special
160 157 characters (sometimes called metacharacters). If used without this protection,
161 158 syntax errors can result or implementation extensions can be triggered. For
162 159 example, the KornShell supports a series of extensions based on parentheses in
163 160 patterns; see \fBksh\fR(1)
164 161 .SS "Patterns Matching Multiple Characters"
165 -.sp
166 162 .LP
167 163 The following rules are used to construct \fIpatterns matching multiple
168 164 characters\fR from \fIpatterns matching a single character\fR:
169 165 .RS +4
170 166 .TP
171 167 .ie t \(bu
172 168 .el o
173 169 The asterisk (*) is a pattern that will match any string, including the null
174 170 string.
175 171 .RE
176 172 .RS +4
177 173 .TP
178 174 .ie t \(bu
179 175 .el o
180 176 The concatenation of \fIpatterns matching a single character\fR is a valid
181 177 pattern that will match the concatenation of the single characters or collating
182 178 elements matched by each of the concatenated patterns.
183 179 .RE
184 180 .RS +4
185 181 .TP
186 182 .ie t \(bu
187 183 .el o
188 184 The concatenation of one or more \fIpatterns matching a single character\fR
189 185 with one or more asterisks is a valid pattern. In such patterns, each asterisk
190 186 will match a string of zero or more characters, matching the greatest possible
191 187 number of characters that still allows the remainder of the pattern to match
192 188 the string.
193 189 .RE
194 190 .sp
195 191 .LP
196 192 Since each asterisk matches zero or more occurrences, the patterns \fBa*b\fR
197 193 and \fBa**b\fR have identical functionality.
198 194 .sp
199 195 .LP
200 196 Examples:
201 197 .sp
202 198 .ne 2
203 199 .na
204 200 \fB\fBa[bc]\fR \fR
205 201 .ad
206 202 .RS 10n
207 203 matches the strings \fBab\fR and \fBac\fR.
208 204 .RE
209 205
210 206 .sp
211 207 .ne 2
212 208 .na
213 209 \fB\fBa*d\fR \fR
214 210 .ad
215 211 .RS 10n
216 212 matches the strings \fBad\fR, \fBabd\fR and \fBabcd\fR, but not the string
217 213 \fBabc\fR.
218 214 .RE
219 215
220 216 .sp
221 217 .ne 2
222 218 .na
223 219 \fB\fBa*d*\fR \fR
224 220 .ad
225 221 .RS 10n
226 222 matches the strings \fBad\fR, \fBabcd\fR, \fBabcdef\fR, \fBaaaad\fR and
227 223 \fBadddd\fR.
228 224 .RE
229 225
230 226 .sp
|
↓ open down ↓ |
55 lines elided |
↑ open up ↑ |
231 227 .ne 2
232 228 .na
233 229 \fB\fB*a*d\fR \fR
234 230 .ad
235 231 .RS 10n
236 232 matches the strings \fBad\fR, \fBabcd\fR, \fBefabcd\fR, \fBaaaad\fR and
237 233 \fBadddd\fR.
238 234 .RE
239 235
240 236 .SS "Patterns Used for Filename Expansion"
241 -.sp
242 237 .LP
243 238 The rules described so far in \fBPatterns\fR \fBMatching\fR \fBMultiple\fR
244 239 \fBCharacters\fR and \fBPatterns\fR \fBMatching\fR \fBa\fR \fBSingle\fR
245 240 \fBCharacter\fR are qualified by the following rules that apply when pattern
246 241 matching notation is used for filename expansion.
247 242 .RS +4
248 243 .TP
249 244 1.
250 245 The slash character in a pathname must be explicitly matched by using one
251 246 or more slashes in the pattern; it cannot be matched by the asterisk or
252 247 question-mark special characters or by a bracket expression. Slashes in the
253 248 pattern are identified before bracket expressions; thus, a slash cannot be
254 249 included in a pattern bracket expression used for filename expansion. For
255 250 example, the pattern \fBa[b/c]d\fR will not match such pathnames as \fBabd\fR
256 251 or \fBa/d\fR. It will only match a pathname of literally \fBa[b/c]d\fR.
257 252 .RE
258 253 .RS +4
259 254 .TP
260 255 2.
261 256 If a filename begins with a period (.), the period must be explicitly
262 257 matched by using a period as the first character of the pattern or immediately
263 258 following a slash character. The leading period will not be matched by:
264 259 .sp
265 260 \(bu the asterisk or question-mark special characters
266 261 .sp
267 262 \(bu a bracket expression containing a non-matching list, such as:
268 263 .sp
269 264 \fB[!a]\fR
270 265 .sp
271 266 a range expression, such as:
272 267 .sp
273 268 \fB[%\(mi0]\fR
274 269 .sp
275 270 or a character class expression, such as:
276 271 .sp
277 272 \fB[[:punct:]]\fR
278 273 .sp
279 274 It is unspecified whether an explicit period in a bracket expression matching
280 275 list, such as:
281 276 .sp
282 277 \fB[.abc]\fR
283 278 .sp
284 279 can match a leading period in a filename.
285 280 .RE
286 281 .RS +4
287 282 .TP
288 283 3.
289 284 Specified patterns are matched against existing filenames and pathnames, as
290 285 appropriate. Each component that contains a pattern character requires read
291 286 permission in the directory containing that component. Any component, except
292 287 the last, that does not contain a pattern character requires search permission.
293 288 For example, given the pattern:
294 289 .sp
295 290 \fB/foo/bar/x*/bam\fR
296 291 .sp
297 292 search permission is needed for directories \fB/\fR and \fBfoo\fR, search and
|
↓ open down ↓ |
46 lines elided |
↑ open up ↑ |
298 293 read permissions are needed for directory \fBbar\fR, and search permission is
299 294 needed for each \fBx*\fR directory.
300 295 .sp
301 296 If the pattern matches any existing filenames or pathnames, the pattern will be
302 297 replaced with those filenames and pathnames, sorted according to the collating
303 298 sequence in effect in the current locale. If the pattern contains an invalid
304 299 bracket expression or does not match any existing filenames or pathnames, the
305 300 pattern string is left unchanged.
306 301 .RE
307 302 .SH SEE ALSO
308 -.sp
309 303 .LP
310 304 \fBfind\fR(1), \fBksh\fR(1), \fBfnmatch\fR(3C), \fBregex\fR(5)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX