1FNMATCH(3P)                POSIX Programmer's Manual               FNMATCH(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       fnmatch — match a filename string or a pathname
13

SYNOPSIS

15       #include <fnmatch.h>
16
17       int fnmatch(const char *pattern, const char *string, int flags);
18

DESCRIPTION

20       The fnmatch() function shall match patterns as described in  the  Shell
21       and Utilities volume of POSIX.1‐2017, Section 2.13.1, Patterns Matching
22       a Single Character and Section 2.13.2, Patterns Matching Multiple Char‐
23       acters.   It  checks the string specified by the string argument to see
24       if it matches the pattern specified by the pattern argument.
25
26       The flags argument shall  modify  the  interpretation  of  pattern  and
27       string.   It  is  the bitwise-inclusive OR of zero or more of the flags
28       defined in <fnmatch.h>.  If the FNM_PATHNAME flag is set in flags, then
29       a  <slash>  character  ('/') in string shall be explicitly matched by a
30       <slash> in pattern; it shall not be matched by either the <asterisk> or
31       <question-mark> special characters, nor by a bracket expression. If the
32       FNM_PATHNAME flag is not set, the <slash> character shall be treated as
33       an ordinary character.
34
35       If FNM_NOESCAPE is not set in flags, a <backslash> character in pattern
36       followed by any other character shall match that  second  character  in
37       string.   In  particular, "\\" shall match a <backslash> in string.  If
38       pattern ends with an unescaped <backslash>, fnmatch()  shall  return  a
39       non-zero   value   (indicating  either  no  match  or  an  error).   If
40       FNM_NOESCAPE is set, a <backslash> character shall  be  treated  as  an
41       ordinary character.
42
43       If FNM_PERIOD is set in flags, then a leading <period> ('.')  in string
44       shall match a <period> in pattern; as described by rule 2 in the  Shell
45       and Utilities volume of POSIX.1‐2017, Section 2.13.3, Patterns Used for
46       Filename Expansion where the location of ``leading''  is  indicated  by
47       the value of FNM_PATHNAME:
48
49        *  If  FNM_PATHNAME  is  set,  a  <period> is ``leading'' if it is the
50           first character in string or if it immediately follows a <slash>.
51
52        *  If FNM_PATHNAME is not set, a <period> is ``leading'' only if it is
53           the first character of string.
54
55       If  FNM_PERIOD  is  not set, then no special restrictions are placed on
56       matching a period.
57

RETURN VALUE

59       If string matches the pattern  specified  by  pattern,  then  fnmatch()
60       shall   return  0.  If  there  is  no  match,  fnmatch()  shall  return
61       FNM_NOMATCH, which is defined in  <fnmatch.h>.   If  an  error  occurs,
62       fnmatch() shall return another non-zero value.
63

ERRORS

65       No errors are defined.
66
67       The following sections are informative.
68

EXAMPLES

70       None.
71

APPLICATION USAGE

73       The  fnmatch()  function  has  two  major  uses. It could be used by an
74       application or utility that needs to read a directory and apply a  pat‐
75       tern against each entry. The find utility is an example of this. It can
76       also be used by the pax utility to process its pattern operands, or  by
77       applications that need to match strings in a similar manner.
78
79       The  name  fnmatch()  is  intended to imply filename match, rather than
80       pathname match. The default action of this function is to  match  file‐
81       name strings, rather than pathnames, since it gives no special signifi‐
82       cance to the <slash> character. With the FNM_PATHNAME  flag,  fnmatch()
83       does match pathnames, but without tilde expansion, parameter expansion,
84       or special treatment for a <period> at the beginning of a filename.
85

RATIONALE

87       This function replaced the REG_FILENAME flag of regcomp() in early pro‐
88       posals  of  this volume of POSIX.1‐2017. It provides virtually the same
89       functionality as  the  regcomp()  and  regexec()  functions  using  the
90       REG_FILENAME and REG_FSLASH flags (the REG_FSLASH flag was proposed for
91       regcomp(), and would have had the opposite effect  from  FNM_PATHNAME),
92       but with a simpler function and less system overhead.
93

FUTURE DIRECTIONS

95       None.
96

SEE ALSO

98       glob(), Section 2.6, Word Expansions
99
100       The Base Definitions volume of POSIX.1‐2017, <fnmatch.h>
101
103       Portions  of  this text are reprinted and reproduced in electronic form
104       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
105       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
106       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
107       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
108       event of any discrepancy between this version and the original IEEE and
109       The  Open Group Standard, the original IEEE and The Open Group Standard
110       is the referee document. The original Standard can be  obtained  online
111       at http://www.opengroup.org/unix/online.html .
112
113       Any  typographical  or  formatting  errors that appear in this page are
114       most likely to have been introduced during the conversion of the source
115       files  to  man page format. To report such errors, see https://www.ker
116       nel.org/doc/man-pages/reporting_bugs.html .
117
118
119
120IEEE/The Open Group                  2017                          FNMATCH(3P)
Impressum