usr/src/man/man3c/fnmatch.3c

   1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission
   3 .\" to reproduce portions of its copyrighted documentation.
   4 .\"
   5 .\" Original documentation from The Open Group can be obtained online at
   6 .\" http://www.opengroup.org/bookstore/.
   7 .\"
   8 .\" The Institute of Electrical and Electronics Engineers and The Open Group,
   9 .\" have given us permission to reprint portions of their documentation. In the
  10 .\" following statement, the phrase "this text" refers to portions of the system
  11 .\" documentation.
  12 .\"
  13 .\" Portions of this text are reprinted and reproduced in electronic form in the
  14 .\" Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for
  15 .\" Information Technology -- Portable Operating System Interface (POSIX),
  16 .\" The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the
  17 .\" Institute of Electrical and Electronics Engineers, Inc and The Open Group.
  18 .\"
  19 .\" In the event of any discrepancy between these versions and the original
  20 .\" IEEE and The Open Group Standard, the original IEEE and The Open Group
  21 .\" Standard is the referee document.
  22 .\"
  23 .\" The original Standard can be obtained online at
  24 .\" http://www.opengroup.org/unix/online.html.
  25 .\"
  26 .\" This notice shall appear on any product containing this material.
  27 .\"
  28 .\" The contents of this file are subject to the terms of the
  29 .\" Common Development and Distribution License (the "License").
  30 .\" You may not use this file except in compliance with the License.
  31 .\"
  32 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  33 .\" or http://www.opensolaris.org/os/licensing.
  34 .\" See the License for the specific language governing permissions
  35 .\" and limitations under the License.
  36 .\"
  37 .\" When distributing Covered Code, include this CDDL HEADER in each
  38 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  39 .\" If applicable, add the following below this CDDL HEADER, with the
  40 .\" fields enclosed by brackets "[]" replaced with your own identifying
  41 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  42 .\"
  43 .\"
  44 .\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved
  45 .\" Portions Copyright (c) 2002, Sun Microsystems, Inc.  All Rights Reserved
  46 .\" Copyright 2017 Nexenta Systems, Inc.
  47 .\"
  48 .Dd August 14, 2017
  49 .Dt FNMATCH 3C
  50 .Os
  51 .Sh NAME
  52 .Nm fnmatch
  53 .Nd match filename or path name
  54 .Sh LIBRARY
  55 .Lb libc
  56 .Sh SYNOPSIS
  57 .In fnmatch.h
  58 .Ft int
  59 .Fo fnmatch
  60 .Fa "const char *pattern"
  61 .Fa "const char *string"
  62 .Fa "int flags"
  63 .Fc
  64 .Sh DESCRIPTION
  65 The
  66 .Fn fnmatch
  67 function matches patterns as described on the
  68 .Xr fnmatch 5
  69 manual page
  70 .Po with the exceptions noted in the
  71 .Sx STANDARDS
  72 .Pc .
  73 It checks the
  74 .Fa string
  75 argument to see if it matches the
  76 .Fa pattern
  77 argument.
  78 .Pp
  79 The
  80 .Fa flags
  81 argument modifies the interpretation of
  82 .Fa pattern
  83 and
  84 .Fa string .
  85 It is the bitwise inclusive OR of zero or more of the following flags defined in
  86 the header
  87 .In fnmatch.h .
  88 .Bl -tag -width "FNM_LEADING_DIR"
  89 .It Dv FNM_PATHNAME
  90 If set, a slash
  91 .Pq Qq /
  92 character in
  93 .Fa string
  94 will be explicitly matched by a slash in
  95 .Fa pattern ;
  96 it will not be matched by either the asterisk
  97 .Pq Qq *
  98 or question-mark
  99 .Pq Qq \&?
 100 special characters, nor by a bracket
 101 .Pq Qq []
 102 expression.
 103 .sp
 104 If not set, the slash character is treated as an ordinary character.
 105 .It Dv FNM_IGNORECASE
 106 If set, the
 107 .Fa string
 108 will be transliterated to lower case before doing the actual match.
 109 This transliteration is done using
 110 .Xr towlower_l 3C ,
 111 using the locale of the current thread.
 112 If no locale is set, then the global locale is used instead.
 113 .Pp
 114 If not set, the match will use
 115 .Fa string
 116 with no changes, making the match case-sensitive.
 117 .Pp
 118 For compatibility with
 119 .Fx
 120 implementation of
 121 .Fn fnmatch ,
 122 header
 123 .In fnmatch.h
 124 provides the
 125 .Dv FNM_FOLDCASE
 126 flag having the same meaning.
 127 .It Dv FNM_NOESCAPE
 128 If not set, a backslash character
 129 .Pq Qq \e
 130 in
 131 .Fa pattern
 132 followed by any other character will match that second character in
 133 .Fa string .
 134 In particular,
 135 .Qq \e\e
 136 will match a backslash in
 137 .Fa string .
 138 .Pp
 139 If set, a backslash character will be treated as an ordinary character.
 140 .It Dv FNM_PERIOD
 141 If set, a leading period in
 142 .Fa string
 143 will match a period in
 144 .Fa pattern ;
 145 where the location of
 146 .Qq leading
 147 is indicated by the value of
 148 .Dv FNM_PATHNAME :
 149 .Bl -bullet
 150 .It
 151 If
 152 .Dv FNM_PATHNAME
 153 is set, a period is
 154 .Qq leading
 155 if it is the first character in
 156 .Fa string
 157 or if it immediately follows a slash.
 158 .It
 159 If
 160 .Dv FNM_PATHNAME
 161 is not set, a period is
 162 .Qq leading
 163 only if it is the first character of
 164 .Fa string .
 165 .El
 166 .Pp
 167 If not set, no special restrictions are placed on matching a period.
 168 .It Dv FNM_LEADING_DIR
 169 Match if
 170 .Fa pattern
 171 matches initial segment of
 172 .Fa string
 173 which is followed by a slash.
 174 .El
 175 .Sh RETURN VALUES
 176 If
 177 .Fa string
 178 matches the pattern specified by
 179 .Fa pattern ,
 180 then
 181 .Fn fnmatch
 182 returns 0.
 183 If there is no match,
 184 .Fn fnmatch
 185 returns
 186 .Dv FNM_NOMATCH ,
 187 which is defined in the header
 188 .In fnmatch.h .
 189 If an error occurs,
 190 .Fn fnmatch
 191 returns another non-zero value.
 192 .Sh USAGE
 193 The
 194 .Fn fnmatch
 195 function has two major uses.
 196 It could be used by an application or utility that needs to read a directory and
 197 apply a pattern against each entry.
 198 The
 199 .Xr find 1
 200 utility is an example of this.
 201 It can also be used by the
 202 .Xr pax 1
 203 utility to process its
 204 .Fa pattern
 205 operands, or by applications that need to match strings in a similar manner.
 206 .Pp
 207 The name
 208 .Fn fnmatch
 209 is intended to imply
 210 .Sy filename
 211 match, rather than
 212 .Sy pathname
 213 match.
 214 The default action of this function is to match filenames, rather than path
 215 names, since it gives no special significance to the slash character.
 216 With the
 217 .Dv FNM_PATHNAME
 218 flag,
 219 .Fn fnmatch
 220 does match path names, but without tilde expansion, parameter expansion, or
 221 special treatment for period at the beginning of a filename.
 222 .Sh CODE SET INDEPENDENCE
 223 .Sy Enabled
 224 .Sh INTERFACE STABILITY
 225 .Sy Standard
 226 .Sh MT-LEVEL
 227 .Sy MT-Safe with exceptions
 228 .Pp
 229 The
 230 .Fn fnmatch
 231 function can be used safely in multithreaded applications, as long as
 232 .Xr setlocale 3C
 233 is not being called to change the locale.
 234 .Sh SEE ALSO
 235 .Xr find 1 ,
 236 .Xr pax 1 ,
 237 .Xr glob 3C ,
 238 .Xr setlocale 3C ,
 239 .Xr wordexp 3C ,
 240 .Xr attributes 5 ,
 241 .Xr fnmatch 5 ,
 242 .Xr standards 5
 243 .Sh STANDARDS
 244 The current implementation of the
 245 .Fn fnmatch
 246 function
 247 .Em does not
 248 conform to
 249 .St -p1003.2 .
 250 Collating symbol expressions, equivalence class expressions and
 251 character class expressions are not supported.
 252 .Sh BUGS
 253 The pattern
 254 .Qq *
 255 matches the empty string, even if
 256 .Dv FNM_PATHNAME
 257 is specified.