1
fnmatch(S)
____________________________________________________________
_f_n_m_a_t_c_h_,_ ___f_n_m_c_o_m_p_,_ ___f_n_m_e_x_e_c_,_ ___f_n_m_f_r_e_e_ _-_-_ _m_a_t_c_h_ _f_i_l_e_n_a_m_e_ _a_g_a_i_n_s_t
_p_a_t_t_e_r_n_
Synopsis
#include
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);
int _fnmcomp(fnm_t * _p_f_n_m, const unsigned char * _p_a_t_t_e_r_n, int
_f_l_a_g_s);
int _fnmexec(fnm_t * _p_f_n_m, const unsigned char * _s_t_r_i_n_g);
void _fnmfree(fnm_t * _p_f_n_m);
Description
_f_n_m_a_t_c_h checks _s_t_r_i_n_g to see if it matches the pattern specified
by _p_a_t_t_e_r_n. It is essentially equivalent to a call to ___f_n_m_c_o_m_p,
which, if that succeeds, is then followed by a call to ___f_n_m_e_x_e_c
and then ___f_n_m_f_r_e_e. Its return value is the same as ___f_n_m_c_o_m_p if
that function fails; otherwise its return value is that of
___f_n_m_e_x_e_c.
Data type
The data type _f_n_m___t is a structure containing at least the
following members:
size_t fnm_nsub; /* number of subexpressions */
ssize_t fnm_so[FNM_NSUBEXPR]; /* (sub)expression starting
offsets */
ssize_t fnm_eo[FNM_NSUBEXPR]; /* (sub)expression ending
offsets */
These structure members are set by ___f_n_m_c_o_m_p or ___f_n_m_e_x_e_c and only
when the _F_N_M___S_U_B_E_X_P_R flag is set; otherwise, their values are
indeterminate. _F_N_M___N_S_U_B_E_X_P_R is at least 10 so that back
references ``\1'' through ``\9'' can be handled.
Flags
_f_l_a_g_s is the bitwise inclusive _O_R of zero or more of the flags
defined in the _f_n_m_a_t_c_h_._h header. It modifies the interpretation
of _p_a_t_t_e_r_n and _s_t_r_i_n_g. The following flags can be set:
_F_N_M___P_A_T_H_N_A_M_E
If set, a slash (/) character in _s_t_r_i_n_g must be matched by
an explicit slash in _p_a_t_t_e_r_n, and will not be matched by
meta characters such as an asterisk. If _F_N_M___P_A_T_H_N_A_M_E is
not set, the slash character is treated as an ordinary
character.
_F_N_M___N_O_E_S_C_A_P_E
If set, a backslash character is treated as an ordinary
character. If _F_N_M___N_O_E_S_C_A_P_E is not set, a backslash
character in _p_a_t_t_e_r_n will match the next character as an
ordinary character unless the next character is the null
character, or is a slash and either _F_N_M___P_A_T_H_N_A_M_E or
_F_N_M___C_O_M_P_O_N_E_N_T is set, or is a digit and _F_N_M___E_X_T_E_N_D_E_D is
set. In particular, ``\\'' will match a backslash in
_s_t_r_i_n_g.
_F_N_M___P_E_R_I_O_D
If set, a leading period in _s_t_r_i_n_g must be matched by an
explicit period in _p_a_t_t_e_r_n where the location of
``leading'' is indicated by the value of _F_N_M___P_A_T_H_N_A_M_E:
+ If _F_N_M___P_A_T_H_N_A_M_E 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 _F_N_M___P_A_T_H_N_A_M_E is not set, a period is leading only if
it is the first character of _s_t_r_i_n_g.
If _F_N_M___P_E_R_I_O_D is not set, a period is treated as an
ordinary character.
_F_N_M___B_A_D_R_A_N_G_E
If set, an out-of-order range within brackets will
silently be taken as if only the end points were specified
(so a _[_m_-_a_] will behave like _[_m_a_]); otherwise, the pattern
will fail to compile and _F_N_M___B_A_D_P_A_T will be returned.
_F_N_M___E_X_T_E_N_D_E_D
If set, all ksh pattern matching extensions will be
accepted; otherwise, just the basic meta characters of _*_ ,
_?, and brackets will be special. These extensions include
back references, so a pattern like _a_@_(_x_y_z_)_b_\_1_c will match
the string _a_x_y_z_b_x_y_z_c, assuming that _F_N_M___N_O_E_S_C_A_P_E is not
set.
_F_N_M___B_K_T_E_S_C_A_P_E
If set, backslashes within brackets will quote the next
character; otherwise, backslashes are not special within
brackets.
_F_N_M___R_E_U_S_E
If set, the _f_n_m___t structure whose address is passed to
___f_n_m_c_o_m_p must have been set by a previous call to ___f_n_m_c_o_m_p
without an intervening call to ___f_n_m_f_r_e_e. This allows for
greater efficiency when compiling and matching against a
series of patterns. If _F_N_M___R_E_U_S_E is not set, the _f_n_m___t
structure is assumed to be uninitialized.
_F_N_M___C_O_M_P_O_N_E_N_T
If set, a slash character in _p_a_t_t_e_r_n will end the pattern
to be matched against, the same as if the terminating null
character were reached. Otherwise, slash characters do not
end the pattern.
_F_N_M___U_N_A_N_C_H_O_R_E_D
If set, the match need not include the start of _s_t_r_i_n_g;
otherwise, it must.
_F_N_M___R_E_T_M_I_N_,
_F_N_M___R_E_T_M_A_X
If either of these is set, a successful match does not
have to reach the end of the string; otherwise, a
successful match must include the end of the string. These
two differ in that _F_N_M___R_E_T_M_I_N will return after finding
the shortest valid match, while _F_N_M___R_E_T_M_A_X will return
with the longest. If either of these are set, the length
of the matched portion of _s_t_r_i_n_g is returned, which can be
zero. When neither is set, a successful match is always
indicated by a zero return from ___f_n_m_e_x_e_c. In all cases, a
negative return from ___f_n_m_e_x_e_c indicates an unsuccessful
match. Note that combining _F_N_M___U_N_A_N_C_H_O_R_E_D with either
_F_N_M___R_E_T_M_I_N or _F_N_M___R_E_T_M_A_X severely restricts the utility of
the length-of-match return value.
_F_N_M___S_U_B_E_X_P_R
If set, after a successful ___f_n_m_c_o_m_p, _f_n_m___n_s_u_b will
indicate the number of subexpressions found in the
pattern, and after a successful match, the fnm_so and
fnm_eo arrays in the _f_n_m___t structure will be set to
indicate the start and end offsets into the matched _s_t_r_i_n_g
for the entire match (index zero) and the first
_F_N_M___N_S_U_B_E_X_P_R_-_1 pattern subexpressions (indices one through
_F_N_M___N_S_U_B_E_X_P_R_-_1). Note that there are only subexpressions
in the pattern when _F_N_M___E_X_T_E_N_D_E_D is set and that the array
elements with indices greater than _f_n_m___n_s_u_b have
indeterminate values. An offset value of zero indicates
the start of the string; a negative offset value indicates
a failure to match that subexpression. If _F_N_M___S_U_B_E_X_P_R is
not set, the value of _f_n_m___n_s_u_b and the values in these
arrays are indeterminate, even after a successful compile
or match.
Return values
_f_n_m_a_t_c_h and ___f_n_m_e_x_e_c return zero (or a nonnegative value if
_F_N_M___R_E_T_M_I_N or _F_N_M___R_E_T_M_A_X was set) if _s_t_r_i_n_g matches the compiled
_p_a_t_t_e_r_n. If there is no match, they return a negative value:
_F_N_M___N_O_M_A_T_C_H.
___f_n_m_c_o_m_p returns zero if it successfully compiled _p_a_t_t_e_r_n;
otherwise it returns a negative value such as _F_N_M___B_A_D_P_A_T which
indicates a malformed pattern.
Usage
The name _f_n_m_a_t_c_h indicates that this function is intended to
match filenames rather than pathnames. With _F_N_M___P_A_T_H_N_A_M_E, _f_n_m_a_t_c_h
matches pathnames, but without tilde expansion, or parameter
expansion.
Applications that make heavy use of _f_n_m_a_t_c_h will most likely run
much more efficiently by using the underlying separate compile
and match functions.
References
ffnnmmaattcchh((MM)), gglloobb((SS)), wwoorrddeexxpp((SS))
____________________________________________________________
((cc)) 22000055 TThhee SSCCOO GGrroouupp,, IInncc.. AAllll rriigghhttss rreesseerrvveedd..
_S_C_O_ _O_p_e_n_S_e_r_v_e_r_ _R_e_l_e_a_s_e_ _6_._0_._0_ _-_ _0_1_ _J_u_n_e_ _2_0_0_5