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