illumos-gate Sdiff usr/src/man/man5/fnmatch.5

Print this page

3768 fnmatch(5) is worded poorly

   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

 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

 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

 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)

   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 "Jun 14, 2015"
  13 .SH NAME
  14 fnmatch \- file name pattern matching
  15 .SH DESCRIPTION

  16 .LP
  17 The pattern matching notation described below  is used to specify patterns for
  18 matching strings in the shell. Historically, pattern matching notation is
  19 related to, but slightly different from, the regular expression notation. For
  20 this reason, the description of the rules for this pattern matching notation is
  21 based on the description of regular expression notation described on the
  22 \fBregex\fR(5) manual page.
  23 .SS "Patterns Matching a Single Character"

  24 .LP
  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.

  28 .sp
  29 .LP
  30 An ordinary character is a pattern that matches itself. It can be any character
  31 in the supported character set except for \fINUL\fR, those special shell
  32 characters that require quoting, and the following three special pattern
  33 characters. Matching is based on the bit pattern used for encoding the
  34 character, not on the graphic representation of the character. If any character
  35 (ordinary, shell special, or pattern special) is quoted, that pattern will
  36 match the character itself. The shell special characters always require
  37 quoting.
  38 .sp
  39 .LP
  40 When unquoted and outside a bracket expression, the following three characters
  41 will have special meaning in the specification of patterns:
  42 .sp
  43 .ne 2
  44 .na
  45 \fB\fB?\fR \fR
  46 .ad
  47 .RS 6n

 142 .sp
 143 after quote removal, the backslashes are presented to \fBfind\fR and it treats
 144 them as escape characters. Both precede ordinary characters, so the \fBc\fR and
 145 \fBh\fR represent themselves and \fBecho\fR would be found on many historical
 146 systems (that have it in \fB/bin\fR). To find a file name that contained shell
 147 special characters or pattern characters, both quoting and escaping are
 148 required, such as:
 149 .sp
 150 \fBpax -r .\|.\|. "*a\e\|(\|\e?"\fR
 151 .sp
 152 to extract a filename ending with \fBa(?\fR.
 153 .RE
 154 .sp
 155 .LP
 156 Conforming applications are required to quote or escape the shell special
 157 characters (sometimes called metacharacters). If used without this protection,
 158 syntax errors can result or implementation extensions can be triggered. For
 159 example, the KornShell supports a series of extensions based on parentheses in
 160 patterns; see  \fBksh\fR(1)
 161 .SS "Patterns Matching Multiple Characters"

 162 .LP
 163 The following rules are used to construct \fIpatterns matching multiple
 164 characters\fR from \fIpatterns matching a single character\fR:
 165 .RS +4
 166 .TP
 167 .ie t \(bu
 168 .el o
 169 The asterisk (*) is a pattern that will match any string, including the null
 170 string.
 171 .RE
 172 .RS +4
 173 .TP
 174 .ie t \(bu
 175 .el o
 176 The concatenation of \fIpatterns matching a single character\fR is a valid
 177 pattern that will match the concatenation of the single characters or collating
 178 elements matched by each of the concatenated patterns.
 179 .RE
 180 .RS +4
 181 .TP

 217 .ne 2
 218 .na
 219 \fB\fBa*d*\fR \fR
 220 .ad
 221 .RS 10n
 222 matches the strings \fBad\fR, \fBabcd\fR, \fBabcdef\fR, \fBaaaad\fR and
 223 \fBadddd\fR.
 224 .RE
 225 
 226 .sp
 227 .ne 2
 228 .na
 229 \fB\fB*a*d\fR \fR
 230 .ad
 231 .RS 10n
 232 matches the strings \fBad\fR, \fBabcd\fR, \fBefabcd\fR, \fBaaaad\fR and
 233 \fBadddd\fR.
 234 .RE
 235 
 236 .SS "Patterns Used for Filename Expansion"

 237 .LP
 238 The rules described so far in \fBPatterns\fR \fBMatching\fR \fBMultiple\fR
 239 \fBCharacters\fR and \fBPatterns\fR \fBMatching\fR \fBa\fR \fBSingle\fR
 240 \fBCharacter\fR are qualified by the following rules that apply when pattern
 241 matching notation is used for filename expansion.
 242 .RS +4
 243 .TP
 244 1.
 245 The slash character in a pathname must be explicitly matched by using one
 246 or more slashes in the pattern; it cannot be matched by the asterisk or
 247 question-mark special characters or by a bracket expression. Slashes in the
 248 pattern are identified before bracket expressions; thus, a slash cannot be
 249 included in a pattern bracket expression used for filename expansion. For
 250 example, the pattern \fBa[b/c]d\fR will not match such pathnames as \fBabd\fR
 251 or \fBa/d\fR. It will only match a pathname of literally \fBa[b/c]d\fR.
 252 .RE
 253 .RS +4
 254 .TP
 255 2.
 256 If a filename begins with a period (.), the period must be explicitly

 283 3.
 284 Specified patterns are matched against existing filenames and pathnames,  as
 285 appropriate.  Each component that contains a pattern character requires read
 286 permission in the directory containing that component. Any component, except
 287 the last, that does not contain a pattern character requires search permission.
 288 For example, given the pattern:
 289 .sp
 290 \fB/foo/bar/x*/bam\fR
 291 .sp
 292 search permission is needed for directories \fB/\fR and \fBfoo\fR, search and
 293 read permissions are needed for directory \fBbar\fR, and search permission is
 294 needed for each \fBx*\fR directory.
 295 .sp
 296 If the pattern matches any existing filenames or pathnames, the pattern will be
 297 replaced with those filenames and pathnames, sorted according to the collating
 298 sequence in effect in the current locale. If the pattern contains an invalid
 299 bracket expression or does not match any existing filenames or pathnames, the
 300 pattern string is left unchanged.
 301 .RE
 302 .SH SEE ALSO

 303 .LP
 304 \fBfind\fR(1), \fBksh\fR(1), \fBfnmatch\fR(3C), \fBregex\fR(5)