.rn '' }`
''' $RCSfile: shpat_match.3,v $$Revision: 1.2 $$Date: 2001/09/13 13:45:12 $
'''
''' $Log: shpat_match.3,v $
''' Revision 1.2  2001/09/13 13:45:12  thl
''' revamping and polishing documentation files for release
'''
''' Revision 1.1  2001/08/06 10:51:11  thl
''' add shpat_match from OSSP shpat library
'''
'''
.de Sh
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp
.if t .sp .5v
.if n .sp
..
.de Ip
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.de Vb
.ft CW
.nf
.ne \\$1
..
.de Ve
.ft R

.fi
..
'''
'''
'''     Set up \*(-- to give an unbreakable dash;
'''     string Tr holds user defined translation string.
'''     Bell System Logo is used as a dummy character.
'''
.tr \(*W-|\(bv\*(Tr
.ie n \{\
.ds -- \(*W-
.ds PI pi
.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
.ds L" ""
.ds R" ""
'''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
'''   \*(L" and \*(R", except that they are used on ".xx" lines,
'''   such as .IP and .SH, which do another additional levels of
'''   double-quote interpretation
.ds M" """
.ds S" """
.ds N" """""
.ds T" """""
.ds L' '
.ds R' '
.ds M' '
.ds S' '
.ds N' '
.ds T' '
'br\}
.el\{\
.ds -- \(em\|
.tr \*(Tr
.ds L" ``
.ds R" ''
.ds M" ``
.ds S" ''
.ds N" ``
.ds T" ''
.ds L' `
.ds R' '
.ds M' `
.ds S' '
.ds N' `
.ds T' '
.ds PI \(*p
'br\}
.\"	If the F register is turned on, we'll generate
.\"	index entries out stderr for the following things:
.\"		TH	Title 
.\"		SH	Header
.\"		Sh	Subsection 
.\"		Ip	Item
.\"		X<>	Xref  (embedded
.\"	Of course, you have to process the output yourself
.\"	in some meaninful fashion.
.if \nF \{
.de IX
.tm Index:\\$1\t\\n%\t"\\$2"
..
.nr % 0
.rr F
.\}
.TH shpat_match 3 "19-Aug-1999" "Shpat 1.0.0" "MAX File Name Library"
.UC
.if n .hy 0
.if n .na
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.de CQ          \" put $1 in typewriter font
.ft CW
'if n "\c
'if t \\&\\$1\c
'if n \\&\\$1\c
'if n \&"
\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
'.ft R
..
.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
.	\" AM - accent mark definitions
.bd B 3
.	\" fudge factors for nroff and troff
.if n \{\
.	ds #H 0
.	ds #V .8m
.	ds #F .3m
.	ds #[ \f1
.	ds #] \fP
.\}
.if t \{\
.	ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.	ds #V .6m
.	ds #F 0
.	ds #[ \&
.	ds #] \&
.\}
.	\" simple accents for nroff and troff
.if n \{\
.	ds ' \&
.	ds ` \&
.	ds ^ \&
.	ds , \&
.	ds ~ ~
.	ds ? ?
.	ds ! !
.	ds /
.	ds q
.\}
.if t \{\
.	ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.	ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.	ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.	ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.	ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.	ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
.	ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
.	ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.	ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
.\}
.	\" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.ds oe o\h'-(\w'o'u*4/10)'e
.ds Oe O\h'-(\w'O'u*4/10)'E
.	\" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.	\" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.	ds : e
.	ds 8 ss
.	ds v \h'-1'\o'\(aa\(ga'
.	ds _ \h'-1'^
.	ds . \h'-1'.
.	ds 3 3
.	ds o a
.	ds d- d\h'-1'\(ga
.	ds D- D\h'-1'\(hy
.	ds th \o'bp'
.	ds Th \o'LP'
.	ds ae ae
.	ds Ae AE
.	ds oe oe
.	ds Oe OE
.\}
.rm #[ #] #H #V #F C
.SH "NAME"
\fBshpat_match\fR \- match filename or pathname
.SH "SYNOPSIS"
#include <\fBshpat_match.h\fR>
.PP
int \fBshpat_match\fR(const char *\fIpattern\fR, const char *\fIstring\fR, int \fIflags\fR);
.PP
int \fBshpat_match_hasglobchar\fR(const char *\fIpattern\fR);
.SH "DESCRIPTION"
The \fIshpat_match\fR\|(3) function matches patterns according to the rules used by the
shell.  It checks the string specified by the \fIstring\fR argument to see if it
matches the pattern specified by the \fIpattern\fR argument.
.Sh "Shell Patterns"
A \fIpattern\fR consists of normal characters, which match themselves, and
meta-characters (aka \fIglob chars\fR).  The meta-characters are ``\f(CW!\fR'\*(R',
``\f(CW*\fR'\*(R', ``\f(CW?\fR'\*(R', and ``\f(CW[\fR'\*(R'.  These characters lose their special
meanings if they are quoted with a backslash (``\f(CW\e\fR''). 
.PP
An asterisk (``\f(CW*\fR'') matches any string of characters.  A question mark
(``\f(CW?\fR'') matches any single character.  A left bracket (``\f(CW[\fR'') introduces
a character class.  The end of the character class is indicated by a ``\f(CW]\fR'\*(R';
if the ``\f(CW]\fR'\*(R' is missing then the ``\f(CW[\fR'\*(R' matches a ``\f(CW[\fR'\*(R' rather than
introducing a character class.  A character class matches any of the
characters between the square brackets.  A range of characters may be
specified using a minus sign (``\f(CW-\fR''). The character class may be
complemented/negated by making an exclamation point (``\f(CW!\fR'') the first
character of the character class.
.PP
To include a ``\f(CW]\fR'\*(R' in a character class, make it the first character listed
(after the ``\f(CW!\fR'\*(R', if any).  To include a minus sign, make it the first or
last character listed.
.Sh "Matching Interpretation"
The \fIflags\fR argument modifies the interpretation of \fIpattern\fR and \fIstring\fR
The value of \fIflags\fR is the bitwise inclusive \fI\s-1OR\s0\fR of any of the following
constants, which are defined in the include file \f(CWshpat_match.h\fR.
.Ip "\f(CWSHPAT_M_NOESCAPE\fR" 4
Normally, every occurrence of a backslash (``\f(CW\e\fR'') followed by a character
in \fIpattern\fR is replaced by that character.  This is done to negate any
special meaning for the character.  If the \f(CWFNM_NOESCAPE\fR flag is set, a
backslash character is treated as an ordinary character.
.Ip "\f(CWSHPAT_M_PATHNAME\fR" 4
Slash characters in \fIstring\fR must be explicitly matched by slashes in
\fIpattern\fR If this flag is not set, then slashes are treated as regular
characters.
.Ip "\f(CWSHPAT_M_PERIOD\fR" 4
Leading periods in \fIstring\fR must be explicitly matched by periods in
\fIpattern\fR If this flag is not set, then leading periods are treated as
regular characters.  The definition of ``leading'\*(R' is related to the
specification of \f(CWFNM_PATHNAME\fR A period is always ``leading'\*(R' if it is the
first character in \fIstring\fR Additionally, if \fI\s-1FNM_PATHNAME\s0\fR is set, a period
is ``leading'\*(R' if it immediately follows a slash.
.Ip "\f(CWSHPAT_M_LEADING_DIR\fR" 4
Ignore ``\f(CW/*\fR'\*(R' rest after successful \fIpattern\fR matching.
.Ip "\f(CWSHPAT_M_CASEFOLD\fR" 4
Ignore case distinctions in both the \fIpattern\fR and the \fIstring\fR.
.SH "RETURN VALUES"
The \fIshpat_match\fR\|(3) function returns zero if \fIstring\fR matches the pattern
specified by \fIpattern\fR, otherwise, it returns the value \f(CWFNM_NOMATCH\fR.
.SH "BUGS"
The pattern ``\f(CW*\fR'\*(R' matches the empty string, even if \f(CWFNM_PATHNAME\fR is
specified.
.SH "SEE ALSO"
\fIsh\fR\|(1), \fIshpat_glob\fR\|(3).
.SH "STANDARDS"
The \fIshpat_match\fR\|(3) function conforms to IEEE Std1003.2 (``POSIX.2'')
.SH "HISTORY"
The \fIshpat_match\fR\|(3) function is derived from the \fIfnmatch\fR\|(3) function of FreeBSD
3.1 which itself derived it from 4.4BSD.  The \fIshpat_match_hasglobchar\fR\|(3)
function is derived from the \fIap_is_fnmatch\fR\|(3) function of Apache 1.3.

.rn }` ''
.IX Title "shpat_match 3"
.IX Name "B<shpat_match> - match filename or pathname"

.IX Header "NAME"

.IX Header "SYNOPSIS"

.IX Header "DESCRIPTION"

.IX Subsection "Shell Patterns"

.IX Subsection "Matching Interpretation"

.IX Item "\f(CWSHPAT_M_NOESCAPE\fR"

.IX Item "\f(CWSHPAT_M_PATHNAME\fR"

.IX Item "\f(CWSHPAT_M_PERIOD\fR"

.IX Item "\f(CWSHPAT_M_LEADING_DIR\fR"

.IX Item "\f(CWSHPAT_M_CASEFOLD\fR"

.IX Header "RETURN VALUES"

.IX Header "BUGS"

.IX Header "SEE ALSO"

.IX Header "STANDARDS"

.IX Header "HISTORY"