FNMATCH(3)                 POSIX Programmer's Manual                FNMATCH(3)



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

NNAAMMEE
       fnmatch -- match a filename string or a pathname

SSYYNNOOPPSSIISS
       #include <fnmatch.h>

       int fnmatch(const char *_p_a_t_t_e_r_n, const char *_s_t_r_i_n_g, int _f_l_a_g_s);

DDEESSCCRRIIPPTTIIOONN
       The _f_n_m_a_t_c_h() function shall match patterns as described in the Shell
       and Utilities volume of POSIX.1-2017, _S_e_c_t_i_o_n _2_._1_3_._1, _P_a_t_t_e_r_n_s _M_a_t_c_h_i_n_g
       _a _S_i_n_g_l_e _C_h_a_r_a_c_t_e_r and _S_e_c_t_i_o_n _2_._1_3_._2, _P_a_t_t_e_r_n_s _M_a_t_c_h_i_n_g _M_u_l_t_i_p_l_e
       _C_h_a_r_a_c_t_e_r_s.  It checks the string specified by the _s_t_r_i_n_g argument to
       see if it matches the pattern specified by the _p_a_t_t_e_r_n argument.

       The _f_l_a_g_s argument shall modify the interpretation of _p_a_t_t_e_r_n and
       _s_t_r_i_n_g.  It is the bitwise-inclusive OR of zero or more of the flags
       defined in _<_f_n_m_a_t_c_h_._h_>.  If the FNM_PATHNAME flag is set in _f_l_a_g_s, then
       a <slash> character (''//'') in _s_t_r_i_n_g shall be explicitly matched by a
       <slash> in _p_a_t_t_e_r_n; it shall not be matched by either the <asterisk> or
       <question-mark> special characters, nor by a bracket expression. If the
       FNM_PATHNAME flag is not set, the <slash> character shall be treated as
       an ordinary character.

       If FNM_NOESCAPE is not set in _f_l_a_g_s, a <backslash> character in _p_a_t_t_e_r_n
       followed by any other character shall match that second character in
       _s_t_r_i_n_g.  In particular, ""\\\\"" shall match a <backslash> in _s_t_r_i_n_g.  If
       _p_a_t_t_e_r_n ends with an unescaped <backslash>, _f_n_m_a_t_c_h() shall return a
       non-zero value (indicating either no match or an error).  If
       FNM_NOESCAPE is set, a <backslash> character shall be treated as an
       ordinary character.

       If FNM_PERIOD is set in _f_l_a_g_s, then a leading <period> (''..'')  in _s_t_r_i_n_g
       shall match a <period> in _p_a_t_t_e_r_n; as described by rule 2 in the Shell
       and Utilities volume of POSIX.1-2017, _S_e_c_t_i_o_n _2_._1_3_._3, _P_a_t_t_e_r_n_s _U_s_e_d _f_o_r
       _F_i_l_e_n_a_m_e _E_x_p_a_n_s_i_o_n where the location of ``leading'' is indicated by
       the value of FNM_PATHNAME:

        *  If FNM_PATHNAME is set, a <period> is ``leading'' if it is the
           first character in _s_t_r_i_n_g or if it immediately follows a <slash>.

        *  If FNM_PATHNAME is not set, a <period> is ``leading'' only if it is
           the first character of _s_t_r_i_n_g.

       If FNM_PERIOD is not set, then no special restrictions are placed on
       matching a period.

RREETTUURRNN VVAALLUUEE
       If _s_t_r_i_n_g matches the pattern specified by _p_a_t_t_e_r_n, then _f_n_m_a_t_c_h()
       shall return 0. If there is no match, _f_n_m_a_t_c_h() shall return
       FNM_NOMATCH, which is defined in _<_f_n_m_a_t_c_h_._h_>.  If an error occurs,
       _f_n_m_a_t_c_h() shall return another non-zero value.

EERRRROORRSS
       No errors are defined.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       The _f_n_m_a_t_c_h() function has two major uses. It could be used by an
       application or utility that needs to read a directory and apply a
       pattern against each entry. The _f_i_n_d utility is an example of this. It
       can also be used by the _p_a_x utility to process its _p_a_t_t_e_r_n operands, or
       by applications that need to match strings in a similar manner.

       The name _f_n_m_a_t_c_h() is intended to imply _f_i_l_e_n_a_m_e match, rather than
       _p_a_t_h_n_a_m_e match. The default action of this function is to match
       filename strings, rather than pathnames, since it gives no special
       significance to the <slash> character. With the FNM_PATHNAME flag,
       _f_n_m_a_t_c_h() does match pathnames, but without tilde expansion, parameter
       expansion, or special treatment for a <period> at the beginning of a
       filename.

RRAATTIIOONNAALLEE
       This function replaced the REG_FILENAME flag of _r_e_g_c_o_m_p() in early
       proposals of this volume of POSIX.1-2017. It provides virtually the
       same functionality as the _r_e_g_c_o_m_p() and _r_e_g_e_x_e_c() functions using the
       REG_FILENAME and REG_FSLASH flags (the REG_FSLASH flag was proposed for
       _r_e_g_c_o_m_p(), and would have had the opposite effect from FNM_PATHNAME),
       but with a simpler function and less system overhead.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _g_l_o_b(), _S_e_c_t_i_o_n _2_._6, _W_o_r_d _E_x_p_a_n_s_i_o_n_s

       The Base Definitions volume of POSIX.1-2017, <<ffnnmmaattcchh..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  In the event of any discrepancy between this version and the
       original IEEE and The Open Group Standard, the original IEEE and The
       Open Group Standard is the referee document. The original Standard can
       be obtained online at http://www.opengroup.org/unix/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2017                           FNMATCH(3)
