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