Print this page
3768 fnmatch(5) is worded poorly
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man5/fnmatch.5.man.txt
+++ new/usr/src/man/man5/fnmatch.5.man.txt
1 1 FNMATCH(5) Standards, Environments, and Macros FNMATCH(5)
2 2
3 3
4 4
5 5 NAME
6 6 fnmatch - file name pattern matching
|
↓ open down ↓ |
6 lines elided |
↑ open up ↑ |
7 7
8 8 DESCRIPTION
9 9 The pattern matching notation described below is used to specify
10 10 patterns for matching strings in the shell. Historically, pattern
11 11 matching notation is related to, but slightly different from, the
12 12 regular expression notation. For this reason, the description of the
13 13 rules for this pattern matching notation is based on the description of
14 14 regular expression notation described on the regex(5) manual page.
15 15
16 16 Patterns Matching a Single Character
17 - The following patterns matching a single character match a single
18 - character: ordinary characters, special pattern characters and pattern
19 - bracket expressions. The pattern bracket expression will also match a
20 - single collating element.
17 + The following patterns match a single character: ordinary characters,
18 + special pattern characters and pattern bracket expressions. The pattern
19 + bracket expression will also match a single collating element.
21 20
22 21
23 22 An ordinary character is a pattern that matches itself. It can be any
24 23 character in the supported character set except for NUL, those special
25 24 shell characters that require quoting, and the following three special
26 25 pattern characters. Matching is based on the bit pattern used for
27 26 encoding the character, not on the graphic representation of the
28 27 character. If any character (ordinary, shell special, or pattern
29 28 special) is quoted, that pattern will match the character itself. The
30 29 shell special characters always require quoting.
31 30
32 31
33 32 When unquoted and outside a bracket expression, the following three
34 33 characters will have special meaning in the specification of patterns:
35 34
36 35 ?
37 36 A question-mark is a pattern that will match any character.
38 37
39 38
40 39 *
41 40 An asterisk is a pattern that will match multiple characters, as
42 41 described in Patterns Matching Multiple Characters, below.
43 42
44 43
45 44 [
46 45 The open bracket will introduce a pattern bracket expression.
47 46
48 47
49 48
50 49 The description of basic regular expression bracket expressions on the
51 50 regex(5) manual page also applies to the pattern bracket expression,
52 51 except that the exclamation-mark character ( ! ) replaces the
53 52 circumflex character (^) in its role in a non-matching list in the
54 53 regular expression notation. A bracket expression starting with an
55 54 unquoted circumflex character produces unspecified results.
56 55
57 56
58 57 The restriction on a circumflex in a bracket expression is to allow
59 58 implementations that support pattern matching using the circumflex as
60 59 the negation character in addition to the exclamation-mark. A portable
61 60 application must use something like [\^!] to match either character.
62 61
63 62
64 63 When pattern matching is used where shell quote removal is not
65 64 performed (such as in the argument to the find -name primary when find
66 65 is being called using one of the exec functions, or in the pattern
67 66 argument to the fnmatch(3C) function, special characters can be escaped
68 67 to remove their special meaning by preceding them with a backslash
69 68 character. This escaping backslash will be discarded. The sequence \\
70 69 represents one literal backslash. All of the requirements and effects
71 70 of quoting on ordinary, shell special and special pattern characters
72 71 will apply to escaping in this context.
73 72
74 73
75 74 Both quoting and escaping are described here because pattern matching
76 75 must work in three separate circumstances:
77 76
78 77 o Calling directly upon the shell, such as in pathname
79 78 expansion or in a case statement. All of the following will
80 79 match the string or file abc:
81 80
82 81
83 82
84 83
85 84 abc "abc" a"b"c a\bc a[b]c
86 85 a["b"]c a[\b]c a["\b"]c a?c a*c
87 86
88 87 The following will not:
89 88
90 89
91 90
92 91
93 92 "a?c" a\*c a\[b]c
94 93
95 94
96 95 o Calling a utility or function without going through a shell,
97 96 as described for find(1) and the function fnmatch(3C)
98 97
99 98 o Calling utilities such as find, cpio, tar or pax through the
100 99 shell command line. In this case, shell quote removal is
101 100 performed before the utility sees the argument. For
102 101 example, in:
103 102
104 103 find /bin -name e\c[\h]o -print
105 104
106 105 after quote removal, the backslashes are presented to find
107 106 and it treats them as escape characters. Both precede
108 107 ordinary characters, so the c and h represent themselves and
109 108 echo would be found on many historical systems (that have it
110 109 in /bin). To find a file name that contained shell special
111 110 characters or pattern characters, both quoting and escaping
112 111 are required, such as:
113 112
114 113 pax -r ... "*a\(\?"
115 114
116 115 to extract a filename ending with a(?.
117 116
118 117
119 118 Conforming applications are required to quote or escape the shell
120 119 special characters (sometimes called metacharacters). If used without
121 120 this protection, syntax errors can result or implementation extensions
122 121 can be triggered. For example, the KornShell supports a series of
123 122 extensions based on parentheses in patterns; see ksh(1)
124 123
125 124 Patterns Matching Multiple Characters
126 125 The following rules are used to construct patterns matching multiple
127 126 characters from patterns matching a single character:
128 127
129 128 o The asterisk (*) is a pattern that will match any string,
130 129 including the null string.
131 130
132 131 o The concatenation of patterns matching a single character is
133 132 a valid pattern that will match the concatenation of the
134 133 single characters or collating elements matched by each of
135 134 the concatenated patterns.
136 135
137 136 o The concatenation of one or more patterns matching a single
138 137 character with one or more asterisks is a valid pattern. In
139 138 such patterns, each asterisk will match a string of zero or
140 139 more characters, matching the greatest possible number of
141 140 characters that still allows the remainder of the pattern to
142 141 match the string.
143 142
144 143
145 144 Since each asterisk matches zero or more occurrences, the patterns a*b
146 145 and a**b have identical functionality.
147 146
148 147
149 148 Examples:
150 149
151 150 a[bc]
152 151 matches the strings ab and ac.
153 152
154 153
155 154 a*d
156 155 matches the strings ad, abd and abcd, but not the string abc.
157 156
158 157
159 158 a*d*
160 159 matches the strings ad, abcd, abcdef, aaaad and adddd.
161 160
162 161
163 162 *a*d
164 163 matches the strings ad, abcd, efabcd, aaaad and adddd.
165 164
166 165
167 166 Patterns Used for Filename Expansion
168 167 The rules described so far in Patterns Matching Multiple Characters and
169 168 Patterns Matching a Single Character are qualified by the following
170 169 rules that apply when pattern matching notation is used for filename
171 170 expansion.
172 171
173 172 1. The slash character in a pathname must be explicitly matched
174 173 by using one or more slashes in the pattern; it cannot be
175 174 matched by the asterisk or question-mark special characters
176 175 or by a bracket expression. Slashes in the pattern are
177 176 identified before bracket expressions; thus, a slash cannot
178 177 be included in a pattern bracket expression used for
179 178 filename expansion. For example, the pattern a[b/c]d will
180 179 not match such pathnames as abd or a/d. It will only match a
181 180 pathname of literally a[b/c]d.
182 181
183 182 2. If a filename begins with a period (.), the period must be
184 183 explicitly matched by using a period as the first character
185 184 of the pattern or immediately following a slash character.
186 185 The leading period will not be matched by:
187 186
188 187 o the asterisk or question-mark special characters
189 188
190 189 o a bracket expression containing a non-matching list, such
191 190 as:
192 191
193 192 [!a]
194 193
195 194 a range expression, such as:
196 195
197 196 [%-0]
198 197
199 198 or a character class expression, such as:
200 199
201 200 [[:punct:]]
202 201
203 202 It is unspecified whether an explicit period in a bracket
204 203 expression matching list, such as:
205 204
206 205 [.abc]
207 206
208 207 can match a leading period in a filename.
209 208
210 209 3. Specified patterns are matched against existing filenames
211 210 and pathnames, as appropriate. Each component that
212 211 contains a pattern character requires read permission in the
213 212 directory containing that component. Any component, except
214 213 the last, that does not contain a pattern character requires
215 214 search permission. For example, given the pattern:
216 215
217 216 /foo/bar/x*/bam
218 217
219 218 search permission is needed for directories / and foo,
220 219 search and read permissions are needed for directory bar,
221 220 and search permission is needed for each x* directory.
222 221
223 222 If the pattern matches any existing filenames or pathnames,
224 223 the pattern will be replaced with those filenames and
225 224 pathnames, sorted according to the collating sequence in
|
↓ open down ↓ |
195 lines elided |
↑ open up ↑ |
226 225 effect in the current locale. If the pattern contains an
227 226 invalid bracket expression or does not match any existing
228 227 filenames or pathnames, the pattern string is left
229 228 unchanged.
230 229
231 230 SEE ALSO
232 231 find(1), ksh(1), fnmatch(3C), regex(5)
233 232
234 233
235 234
236 - March 28, 1995 FNMATCH(5)
235 + June 14, 2015 FNMATCH(5)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX