1fnmatch(5) Standards, Environments, and Macros fnmatch(5)
2
6 fnmatch - file name pattern matching
7
9 The pattern matching notation described below is used to specify pat‐
10 terns for matching strings in the shell. Historically, pattern matching
11 notation is related to, but slightly different from, the regular
12 expression notation. For this reason, the description of the rules for
13 this pattern matching notation is based on the description of regular
14 expression notation described on the regex(5) manual page.
15 Patterns Matching a Single Character
17 The following patterns matching a single character match a single char‐
18 acter: ordinary characters, special pattern characters and pattern
19 bracket expressions. The pattern bracket expression will also match a
20 single collating element.
21 An ordinary character is a pattern that matches itself. It can be any
24 character in the supported character set except for NUL, those special
25 shell characters that require quoting, and the following three special
26 pattern characters. Matching is based on the bit pattern used for
27 encoding the character, not on the graphic representation of the char‐
28 acter. If any character (ordinary, shell special, or pattern special)
29 is quoted, that pattern will match the character itself. The shell spe‐
30 cial characters always require quoting.
31 When unquoted and outside a bracket expression, the following three
34 characters will have special meaning in the specification of patterns:
35 ? A question-mark is a pattern that will match any character.
37 * An asterisk is a pattern that will match multiple characters, as
40 described in Patterns Matching Multiple Characters, below.
41 [ The open bracket will introduce a pattern bracket expression.
44 The description of basic regular expression bracket expressions on the
48 regex(5) manual page also applies to the pattern bracket expression,
49 except that the exclamation-mark character ( ! ) replaces the circum‐
50 flex character (^) in its role in a non-matching list in the regular
51 expression notation. A bracket expression starting with an unquoted
52 circumflex character produces unspecified results.
53 The restriction on a circumflex in a bracket expression is to allow
56 implementations that support pattern matching using the circumflex as
57 the negation character in addition to the exclamation-mark. A portable
58 application must use something like [\^!] to match either character.
59 When pattern matching is used where shell quote removal is not per‐
62 formed (such as in the argument to the find -name primary when find is
63 being called using one of the exec functions, or in the pattern argu‐
64 ment to the fnmatch(3C) function, special characters can be escaped to
65 remove their special meaning by preceding them with a backslash charac‐
66 ter. This escaping backslash will be discarded. The sequence \\ repre‐
67 sents one literal backslash. All of the requirements and effects of
68 quoting on ordinary, shell special and special pattern characters will
69 apply to escaping in this context.
70 Both quoting and escaping are described here because pattern matching
73 must work in three separate circumstances:
74 o Calling directly upon the shell, such as in pathname expan‐
76 sion or in a case statement. All of the following will match
77 the string or file abc:
78 abc "abc" a"b"c a\bc a[b]c
83 a["b"]c a[\b]c a["\b"]c a?c a*c
84 The following will not:
86 "a?c" a\*c a\[b]c
91 o Calling a utility or function without going through a shell,
94 as described for find(1) and the function fnmatch(3C)
95 o Calling utilities such as find, cpio, tar or pax through the
97 shell command line. In this case, shell quote removal is
98 performed before the utility sees the argument. For exam‐
99 ple, in:
100 find /bin -name e\c[\h]o -print
102 after quote removal, the backslashes are presented to find
104 and it treats them as escape characters. Both precede ordi‐
105 nary characters, so the c and h represent themselves and
106 echo would be found on many historical systems (that have it
107 in /bin). To find a file name that contained shell special
108 characters or pattern characters, both quoting and escaping
109 are required, such as:
110 pax -r ... "*a\(\?"
112 to extract a filename ending with a(?.
114 Conforming applications are required to quote or escape the shell spe‐
117 cial characters (sometimes called metacharacters). If used without this
118 protection, syntax errors can result or implementation extensions can
119 be triggered. For example, the KornShell supports a series of exten‐
120 sions based on parentheses in patterns; see ksh(1)
121 Patterns Matching Multiple Characters
123 The following rules are used to construct patterns matching multiple
124 characters from patterns matching a single character:
125 o The asterisk (*) is a pattern that will match any string,
127 including the null string.
128 o The concatenation of patterns matching a single character is
130 a valid pattern that will match the concatenation of the
131 single characters or collating elements matched by each of
132 the concatenated patterns.
133 o The concatenation of one or more patterns matching a single
135 character with one or more asterisks is a valid pattern. In
136 such patterns, each asterisk will match a string of zero or
137 more characters, matching the greatest possible number of
138 characters that still allows the remainder of the pattern to
139 match the string.
140 Since each asterisk matches zero or more occurrences, the patterns a*b
143 and a**b have identical functionality.
144 Examples:
147 a[bc] matches the strings ab and ac.
149 a*d matches the strings ad, abd and abcd, but not the string abc.
152 a*d* matches the strings ad, abcd, abcdef, aaaad and adddd.
155 *a*d matches the strings ad, abcd, efabcd, aaaad and adddd.
158 Patterns Used for Filename Expansion
161 The rules described so far in Patterns Matching Multiple Characters and
162 Patterns Matching a Single Character are qualified by the following
163 rules that apply when pattern matching notation is used for filename
164 expansion.
165 1. The slash character in a pathname must be explicitly matched
167 by using one or more slashes in the pattern; it cannot be
168 matched by the asterisk or question-mark special characters
169 or by a bracket expression. Slashes in the pattern are iden‐
170 tified before bracket expressions; thus, a slash cannot be
171 included in a pattern bracket expression used for filename
172 expansion. For example, the pattern a[b/c]d will not match
173 such pathnames as abd or a/d. It will only match a pathname
174 of literally a[b/c]d.
175 2. If a filename begins with a period (.), the period must be
177 explicitly matched by using a period as the first character
178 of the pattern or immediately following a slash character.
179 The leading period will not be matched by:
180 · the asterisk or question-mark special characters
182 · a bracket expression containing a non-matching list, such
184 as:
185 [!a]
187 a range expression, such as:
189 [%−0]
191 or a character class expression, such as:
193 [[:punct:]]
195 It is unspecified whether an explicit period in a bracket
197 expression matching list, such as:
198 [.abc]
200 can match a leading period in a filename.
202 3. Specified patterns are matched against existing filenames
204 and pathnames, as appropriate. Each component that con‐
205 tains a pattern character requires read permission in the
206 directory containing that component. Any component, except
207 the last, that does not contain a pattern character requires
208 search permission. For example, given the pattern:
209 /foo/bar/x*/bam
211 search permission is needed for directories / and foo,
213 search and read permissions are needed for directory bar,
214 and search permission is needed for each x* directory.
215 If the pattern matches any existing filenames or pathnames,
217 the pattern will be replaced with those filenames and path‐
218 names, sorted according to the collating sequence in effect
219 in the current locale. If the pattern contains an invalid
220 bracket expression or does not match any existing filenames
221 or pathnames, the pattern string is left unchanged.
222
224 find(1), ksh(1), fnmatch(3C), regex(5)
225SunOS 5.11 28 Mar 1995 fnmatch(5)