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

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