FNMATCH(5) Standards, Environments, and Macros FNMATCH(5) NNAAMMEE fnmatch - file name pattern matching DDEESSCCRRIIPPTTIIOONN The pattern matching notation described below is used to specify patterns for matching strings in the shell. Historically, pattern matching notation is related to, but slightly different from, the regular expression notation. For this reason, the description of the rules for this pattern matching notation is based on the description of regular expression notation described on the rreeggeexx(5) manual page. PPaatttteerrnnss MMaattcchhiinngg aa SSiinnggllee CChhaarraacctteerr The following patterns match a single character: _o_r_d_i_n_a_r_y _c_h_a_r_a_c_t_e_r_s, _s_p_e_c_i_a_l _p_a_t_t_e_r_n _c_h_a_r_a_c_t_e_r_s and _p_a_t_t_e_r_n _b_r_a_c_k_e_t _e_x_p_r_e_s_s_i_o_n_s. The pattern bracket expression will also match a single collating element. An ordinary character is a pattern that matches itself. It can be any character in the supported character set except for _N_U_L, those special shell characters that require quoting, and the following three special pattern characters. Matching is based on the bit pattern used for encoding the character, not on the graphic representation of the character. If any character (ordinary, shell special, or pattern special) is quoted, that pattern will match the character itself. The shell special characters always require quoting. When unquoted and outside a bracket expression, the following three characters will have special meaning in the specification of patterns: ?? A question-mark is a pattern that will match any character. ** An asterisk is a pattern that will match multiple characters, as described in PPaatttteerrnnss MMaattcchhiinngg MMuullttiippllee CChhaarraacctteerrss, below. [[ The open bracket will introduce a pattern bracket expression. The description of basic regular expression bracket expressions on the rreeggeexx(5) manual page also applies to the pattern bracket expression, except that the exclamation-mark character (( !! )) replaces the circumflex character (^^) in its role in a _n_o_n_-_m_a_t_c_h_i_n_g _l_i_s_t in the regular expression notation. A bracket expression starting with an unquoted circumflex character produces unspecified results. The restriction on a circumflex in a bracket expression is to allow implementations that support pattern matching using the circumflex as the negation character in addition to the exclamation-mark. A portable application must use something like [[\\^^!!] to match either character. When pattern matching is used where shell quote removal is not performed (such as in the argument to the ffiinndd --nnaammee primary when ffiinndd is being called using one of the eexxeecc functions, or in the _p_a_t_t_e_r_n argument to the ffnnmmaattcchh(3C) function, special characters can be escaped to remove their special meaning by preceding them with a backslash character. This escaping backslash will be discarded. The sequence \\\\ represents one literal backslash. All of the requirements and effects of quoting on ordinary, shell special and special pattern characters will apply to escaping in this context. Both quoting and escaping are described here because pattern matching must work in three separate circumstances: o Calling directly upon the shell, such as in pathname expansion or in a ccaassee statement. All of the following will match the string or file aabbcc: aabbcc ""aabbcc"" aa""bb""cc aa\\bbcc aa[[bb]]cc aa[[""bb""]]cc aa[[\\bb]]cc aa[[""\\bb""]]cc aa??cc aa**cc The following will not: ""aa??cc"" aa\\**cc aa\\[[bb]]cc o Calling a utility or function without going through a shell, as described for ffiinndd(1) and the function ffnnmmaattcchh(3C) o Calling utilities such as ffiinndd, ccppiioo, ttaarr or ppaaxx through the shell command line. In this case, shell quote removal is performed before the utility sees the argument. For example, in: find /bin -name e\c[\h]o -print after quote removal, the backslashes are presented to ffiinndd and it treats them as escape characters. Both precede ordinary characters, so the cc and hh represent themselves and eecchhoo would be found on many historical systems (that have it in //bbiinn). To find a file name that contained shell special characters or pattern characters, both quoting and escaping are required, such as: ppaaxx --rr ...... ""**aa\\((\\??"" to extract a filename ending with aa((??. Conforming applications are required to quote or escape the shell special characters (sometimes called metacharacters). If used without this protection, syntax errors can result or implementation extensions can be triggered. For example, the KornShell supports a series of extensions based on parentheses in patterns; see kksshh(1) PPaatttteerrnnss MMaattcchhiinngg MMuullttiippllee CChhaarraacctteerrss The following rules are used to construct _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 from _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: o The asterisk (*) is a pattern that will match any string, including the null string. o The concatenation of _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 is a valid pattern that will match the concatenation of the single characters or collating elements matched by each of the concatenated patterns. o The concatenation of one or more _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 with one or more asterisks is a valid pattern. In such patterns, each asterisk will match a string of zero or more characters, matching the greatest possible number of characters that still allows the remainder of the pattern to match the string. Since each asterisk matches zero or more occurrences, the patterns aa**bb and aa****bb have identical functionality. Examples: aa[[bbcc]] matches the strings aabb and aacc. aa**dd matches the strings aadd, aabbdd and aabbccdd, but not the string aabbcc. aa**dd** matches the strings aadd, aabbccdd, aabbccddeeff, aaaaaaaadd and aadddddddd. **aa**dd matches the strings aadd, aabbccdd, eeffaabbccdd, aaaaaaaadd and aadddddddd. PPaatttteerrnnss UUsseedd ffoorr FFiilleennaammee EExxppaannssiioonn The rules described so far in PPaatttteerrnnss MMaattcchhiinngg MMuullttiippllee CChhaarraacctteerrss and PPaatttteerrnnss MMaattcchhiinngg aa SSiinnggllee CChhaarraacctteerr are qualified by the following rules that apply when pattern matching notation is used for filename expansion. 1. The slash character in a pathname must be explicitly matched by using one or more slashes in the pattern; it cannot be matched by the asterisk or question-mark special characters or by a bracket expression. Slashes in the pattern are identified before bracket expressions; thus, a slash cannot be included in a pattern bracket expression used for filename expansion. For example, the pattern aa[[bb//cc]]dd will not match such pathnames as aabbdd or aa//dd. It will only match a pathname of literally aa[[bb//cc]]dd. 2. If a filename begins with a period (.), the period must be explicitly matched by using a period as the first character of the pattern or immediately following a slash character. The leading period will not be matched by: o the asterisk or question-mark special characters o a bracket expression containing a non-matching list, such as: [[!!aa]] a range expression, such as: [[%%--00]] or a character class expression, such as: [[[[::ppuunncctt::]]]] It is unspecified whether an explicit period in a bracket expression matching list, such as: [[..aabbcc]] can match a leading period in a filename. 3. Specified patterns are matched against existing filenames and pathnames, as appropriate. Each component that contains a pattern character requires read permission in the directory containing that component. Any component, except the last, that does not contain a pattern character requires search permission. For example, given the pattern: //ffoooo//bbaarr//xx**//bbaamm search permission is needed for directories // and ffoooo, search and read permissions are needed for directory bbaarr, and search permission is needed for each xx** directory. If the pattern matches any existing filenames or pathnames, the pattern will be replaced with those filenames and pathnames, sorted according to the collating sequence in effect in the current locale. If the pattern contains an invalid bracket expression or does not match any existing filenames or pathnames, the pattern string is left unchanged. SSEEEE AALLSSOO ffiinndd(1), kksshh(1), ffnnmmaattcchh(3C), rreeggeexx(5) June 14, 2015 FNMATCH(5)