]> git.saurik.com Git - apple/libc.git/blob - gen/fnmatch.3
Libc-763.11.tar.gz
[apple/libc.git] / gen / fnmatch.3
1 .\" Copyright (c) 1989, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
3 .\"
4 .\" This code is derived from software contributed to Berkeley by
5 .\" Guido van Rossum.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 4. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)fnmatch.3 8.3 (Berkeley) 4/28/95
31 .\" $FreeBSD: src/lib/libc/gen/fnmatch.3,v 1.19 2007/01/09 00:27:53 imp Exp $
32 .\"
33 .Dd July 18, 2004
34 .Dt FNMATCH 3
35 .Os
36 .Sh NAME
37 .Nm fnmatch
38 .Nd test whether a filename or pathname matches a shell-style pattern
39 .Sh LIBRARY
40 .Lb libc
41 .Sh SYNOPSIS
42 .In fnmatch.h
43 .Ft int
44 .Fn fnmatch "const char *pattern" "const char *string" "int flags"
45 .Sh DESCRIPTION
46 The
47 .Fn fnmatch
48 function
49 matches patterns according to the rules used by the shell.
50 It checks the string specified by the
51 .Fa string
52 argument to see if it matches the pattern specified by the
53 .Fa pattern
54 argument.
55 .Pp
56 The
57 .Fa flags
58 argument modifies the interpretation of
59 .Fa pattern
60 and
61 .Fa string .
62 The value of
63 .Fa flags
64 is the bitwise inclusive
65 .Tn OR
66 of any of the following
67 constants, which are defined in the include file
68 .In fnmatch.h .
69 .Bl -tag -width FNM_PATHNAME
70 .It Dv FNM_NOESCAPE
71 Normally, every occurrence of a backslash
72 .Pq Ql \e
73 followed by a character in
74 .Fa pattern
75 is replaced by that character.
76 This is done to negate any special meaning for the character.
77 If the
78 .Dv FNM_NOESCAPE
79 flag is set, a backslash character is treated as an ordinary character.
80 .It Dv FNM_PATHNAME
81 Slash characters in
82 .Fa string
83 must be explicitly matched by slashes in
84 .Fa pattern .
85 If this flag is not set, then slashes are treated as regular characters.
86 .It Dv FNM_PERIOD
87 Leading periods in
88 .Fa string
89 must be explicitly matched by periods in
90 .Fa pattern .
91 If this flag is not set, then leading periods are treated as regular
92 characters.
93 The definition of
94 .Dq leading
95 is related to the specification of
96 .Dv FNM_PATHNAME .
97 A period is always
98 .Dq leading
99 if it is the first character in
100 .Fa string .
101 Additionally, if
102 .Dv FNM_PATHNAME
103 is set,
104 a period is
105 leading
106 if it immediately follows a slash.
107 .It Dv FNM_LEADING_DIR
108 Ignore
109 .Dq Li /*
110 rest after successful
111 .Fa pattern
112 matching.
113 .It Dv FNM_CASEFOLD
114 Ignore case distinctions in both the
115 .Fa pattern
116 and the
117 .Fa string .
118 .El
119 .Sh RETURN VALUES
120 The
121 .Fn fnmatch
122 function returns zero if
123 .Fa string
124 matches the pattern specified by
125 .Fa pattern .
126 It returns the value
127 .Dv FNM_NOMATCH
128 if no match is found.
129 Otherwise, another non-zero value is returned on error.
130 .Sh LEGACY RETURN VALUES
131 The
132 .Fn fnmatch
133 function returns zero if
134 .Fa string
135 matches the pattern specified by
136 .Fa pattern ;
137 otherwise, it returns the value
138 .Dv FNM_NOMATCH .
139 .Sh SEE ALSO
140 .Xr sh 1 ,
141 .Xr glob 3 ,
142 .Xr regex 3
143 .Sh STANDARDS
144 The current implementation of the
145 .Fn fnmatch
146 function
147 .Em does not
148 conform to
149 .St -p1003.2 .
150 Collating symbol expressions, equivalence class expressions and
151 character class expressions are not supported.
152 .Sh HISTORY
153 The
154 .Fn fnmatch
155 function first appeared in
156 .Bx 4.4 .
157 .Sh BUGS
158 The pattern
159 .Ql *
160 matches the empty string, even if
161 .Dv FNM_PATHNAME
162 is specified.