gen/FreeBSD/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.