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 65The 66.Fn fnmatch 67function matches patterns as described on the 68.Xr fnmatch 5 69manual page 70.Po with the exceptions noted in the 71.Sx STANDARDS 72.Pc . 73It checks the 74.Fa string 75argument to see if it matches the 76.Fa pattern 77argument. 78.Pp 79The 80.Fa flags 81argument modifies the interpretation of 82.Fa pattern 83and 84.Fa string . 85It is the bitwise inclusive OR of zero or more of the following flags defined in 86the header 87.In fnmatch.h . 88.Bl -tag -width "FNM_LEADING_DIR" 89.It Dv FNM_PATHNAME 90If set, a slash 91.Pq Qq / 92character in 93.Fa string 94will be explicitly matched by a slash in 95.Fa pattern ; 96it will not be matched by either the asterisk 97.Pq Qq * 98or question-mark 99.Pq Qq \&? 100special characters, nor by a bracket 101.Pq Qq [] 102expression. 103.sp 104If not set, the slash character is treated as an ordinary character. 105.It Dv FNM_IGNORECASE 106If set, the 107.Fa string 108will be transliterated to lower case before doing the actual match. 109This transliteration is done using 110.Xr towlower_l 3C , 111using the locale of the current thread. 112If no locale is set, then the global locale is used instead. 113.Pp 114If not set, the match will use 115.Fa string 116with no changes, making the match case-sensitive. 117.Pp 118For compatibility with 119.Fx 120implementation of 121.Fn fnmatch , 122header 123.In fnmatch.h 124provides the 125.Dv FNM_FOLDCASE 126flag having the same meaning. 127.It Dv FNM_NOESCAPE 128If not set, a backslash character 129.Pq Qq \e 130in 131.Fa pattern 132followed by any other character will match that second character in 133.Fa string . 134In particular, 135.Qq \e\e 136will match a backslash in 137.Fa string . 138.Pp 139If set, a backslash character will be treated as an ordinary character. 140.It Dv FNM_PERIOD 141If set, a leading period in 142.Fa string 143will match a period in 144.Fa pattern ; 145where the location of 146.Qq leading 147is indicated by the value of 148.Dv FNM_PATHNAME : 149.Bl -bullet 150.It 151If 152.Dv FNM_PATHNAME 153is set, a period is 154.Qq leading 155if it is the first character in 156.Fa string 157or if it immediately follows a slash. 158.It 159If 160.Dv FNM_PATHNAME 161is not set, a period is 162.Qq leading 163only if it is the first character of 164.Fa string . 165.El 166.Pp 167If not set, no special restrictions are placed on matching a period. 168.It Dv FNM_LEADING_DIR 169Match if 170.Fa pattern 171matches initial segment of 172.Fa string 173which is followed by a slash. 174.El 175.Sh RETURN VALUES 176If 177.Fa string 178matches the pattern specified by 179.Fa pattern , 180then 181.Fn fnmatch 182returns 0. 183If there is no match, 184.Fn fnmatch 185returns 186.Dv FNM_NOMATCH , 187which is defined in the header 188.In fnmatch.h . 189If an error occurs, 190.Fn fnmatch 191returns another non-zero value. 192.Sh USAGE 193The 194.Fn fnmatch 195function has two major uses. 196It could be used by an application or utility that needs to read a directory and 197apply a pattern against each entry. 198The 199.Xr find 1 200utility is an example of this. 201It can also be used by the 202.Xr pax 1 203utility to process its 204.Fa pattern 205operands, or by applications that need to match strings in a similar manner. 206.Pp 207The name 208.Fn fnmatch 209is intended to imply 210.Sy filename 211match, rather than 212.Sy pathname 213match. 214The default action of this function is to match filenames, rather than path 215names, since it gives no special significance to the slash character. 216With the 217.Dv FNM_PATHNAME 218flag, 219.Fn fnmatch 220does match path names, but without tilde expansion, parameter expansion, or 221special 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 229The 230.Fn fnmatch 231function can be used safely in multithreaded applications, as long as 232.Xr setlocale 3C 233is 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 244The current implementation of the 245.Fn fnmatch 246function 247.Em does not 248conform to 249.St -p1003.2 . 250Collating symbol expressions, equivalence class expressions and 251character class expressions are not supported. 252.Sh BUGS 253The pattern 254.Qq * 255matches the empty string, even if 256.Dv FNM_PATHNAME 257is specified. 258