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