Sync fnmatch(3) with FreeBSD.
[dragonfly.git] / lib / libc / gen / fnmatch.3
CommitLineData
984263bc
MD
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.
984263bc
MD
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
5659670c 31.\" $FreeBSD: src/lib/libc/gen/fnmatch.3,v 1.19 2007/01/09 00:27:53 imp Exp $
44cb301e 32.\" $DragonFly: src/lib/libc/gen/fnmatch.3,v 1.3 2006/05/26 19:39:36 swildner Exp $
984263bc 33.\"
5659670c 34.Dd July 18, 2004
984263bc
MD
35.Dt FNMATCH 3
36.Os
37.Sh NAME
38.Nm fnmatch
5659670c 39.Nd test whether a filename or pathname matches a shell-style pattern
984263bc
MD
40.Sh LIBRARY
41.Lb libc
42.Sh SYNOPSIS
43.In fnmatch.h
44.Ft int
45.Fn fnmatch "const char *pattern" "const char *string" "int flags"
46.Sh DESCRIPTION
47The
48.Fn fnmatch
49function
50matches patterns according to the rules used by the shell.
51It checks the string specified by the
52.Fa string
53argument to see if it matches the pattern specified by the
54.Fa pattern
55argument.
56.Pp
57The
58.Fa flags
59argument modifies the interpretation of
60.Fa pattern
61and
62.Fa string .
63The value of
64.Fa flags
65is the bitwise inclusive
66.Tn OR
67of any of the following
68constants, which are defined in the include file
44cb301e 69.In fnmatch.h .
984263bc
MD
70.Bl -tag -width FNM_PATHNAME
71.It Dv FNM_NOESCAPE
72Normally, every occurrence of a backslash
73.Pq Ql \e
74followed by a character in
75.Fa pattern
76is replaced by that character.
77This is done to negate any special meaning for the character.
78If the
79.Dv FNM_NOESCAPE
80flag is set, a backslash character is treated as an ordinary character.
81.It Dv FNM_PATHNAME
82Slash characters in
83.Fa string
84must be explicitly matched by slashes in
85.Fa pattern .
86If this flag is not set, then slashes are treated as regular characters.
87.It Dv FNM_PERIOD
88Leading periods in
89.Fa string
90must be explicitly matched by periods in
91.Fa pattern .
92If this flag is not set, then leading periods are treated as regular
93characters.
94The definition of
95.Dq leading
96is related to the specification of
97.Dv FNM_PATHNAME .
98A period is always
99.Dq leading
100if it is the first character in
101.Fa string .
102Additionally, if
103.Dv FNM_PATHNAME
104is set,
105a period is
106leading
107if it immediately follows a slash.
108.It Dv FNM_LEADING_DIR
109Ignore
110.Dq Li /*
111rest after successful
112.Fa pattern
113matching.
114.It Dv FNM_CASEFOLD
5659670c 115Ignore case distinctions in both the
984263bc
MD
116.Fa pattern
117and the
118.Fa string .
119.El
120.Sh RETURN VALUES
121The
122.Fn fnmatch
123function returns zero if
124.Fa string
125matches the pattern specified by
126.Fa pattern ,
127otherwise, it returns the value
128.Dv FNM_NOMATCH .
129.Sh SEE ALSO
130.Xr sh 1 ,
131.Xr glob 3 ,
132.Xr regex 3
133.Sh STANDARDS
5659670c 134The current implementation of the
984263bc 135.Fn fnmatch
5659670c
PA
136function
137.Em does not
138conform to
984263bc 139.St -p1003.2 .
5659670c
PA
140Collating symbol expressions, equivalence class expressions and
141character class expressions are not supported.
984263bc
MD
142.Sh HISTORY
143The
144.Fn fnmatch
145function first appeared in
146.Bx 4.4 .
147.Sh BUGS
148The pattern
149.Ql *
150matches the empty string, even if
151.Dv FNM_PATHNAME
152is specified.