Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
fnmatch(5)	      Standards, Environments, and Macros	    fnmatch(5)

       fnmatch - file name pattern matching

       The  pattern matching notation described	below  is used to specify pat-
       terns for matching strings in the shell.	Historically, pattern matching
       notation	 is  related  to, but slightly different from, the regular ex-
       pression	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  regex(5) manual page.

   Patterns Matching a Single Character
       The following patterns matching a single	character match	a single char-
       acter:  ordinary	 characters,  special  pattern	characters and pattern
       bracket expressions. 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 NUL,	those  special
       shell  characters that require quoting, and the following three special
       pattern characters. Matching is based on	the bit	pattern	used  for  en-
       coding  the character, not on the graphic representation	of the charac-
       ter. 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	Patterns Matching Multiple Characters, below.

       [	The open bracket will introduce	a pattern bracket expression.

       The description of basic	regular	expression bracket expressions on  the
       regex(5)	 manual	 page  also applies to the pattern bracket expression,
       except that the exclamation-mark	character ( ! )	replaces  the  circum-
       flex  character	(^)  in	its role in a non-matching list	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 im-
       plementations that support pattern matching using the circumflex	as the
       negation	 character in addition to the exclamation-mark.	A portable ap-
       plication must use something like [\^!] to match	either character.

       When pattern matching is	used where shell quote	removal	 is  not  per-
       formed  (such as	in the argument	to the find -name primary when find is
       being called using one of the  exec functions, or in the	pattern	 argu-
       ment  to	the fnmatch(3C)	function, special characters can be escaped to
       remove their special meaning by preceding them with a backslash charac-
       ter.  This escaping backslash will be discarded.	The sequence \\	repre-
       sents 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 case statement. All of	the following will match the string or
	    file abc:

	    abc		 "abc"		a"b"c	      a\bc	    a[b]c
	    a["b"]c	 a[\b]c		a["\b"]c      a?c	    a*c

	    The	following will not:

	    "a?c"		 a\*c		       a\[b]c

	 o  Calling  a	utility	 or function without going through a shell, as
	    described for find(1) and the function fnmatch(3C)

	 o  Calling utilities such as find, cpio, tar or pax through the shell
	    command  line.  In this case, shell	quote removal is performed be-
	    fore the utility sees the argument.	 For example, in:

	      find /bin	-name e\c[\h]o -print

       after quote removal, the	backslashes  are  presented  to	 find  and  it
       treats  them as escape characters. Both precede ordinary	characters, so
       the c and h represent themselves	and echo would be found	on  many  his-
       torical	systems	 (that have it in /bin). To find a file	name that con-
       tained shell special characters or pattern characters, both quoting and
       escaping	are required, such as:

	      pax -r ...  "*a\(\?"

       to extract a filename ending with a(?.

  Conforming  applications  are	 required to quote or escape the shell special
  characters (sometimes	called metacharacters).	 If used without this  protec-
  tion,	 syntax	 errors	 can  result or	implementation extensions can be trig-
  gered. For example, the KornShell supports a series of extensions  based  on
  parentheses in patterns; see	ksh(1)

   Patterns Matching Multiple Characters
       The  following  rules  are used to construct patterns matching multiple
       characters from patterns	matching a single character:

	 o  The	asterisk (*) is	a pattern that will match any string,  includ-
	    ing	the null string.

	 o  The	 concatenation	of  patterns  matching a single	character is a
	    valid pattern that will match  the	concatenation  of  the	single
	    characters	or  collating elements matched by each of the concate-
	    nated patterns.

	 o  The	concatenation of one or	more patterns matching a single	 char-
	    acter  with	one or more asterisks is a valid pattern. In such pat-
	    terns, each	asterisk will match a string of	zero or	 more  charac-
	    ters,  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  a*b
       and  a**b have identical	functionality.


       a[bc]	       matches the strings ab and ac.

       a*d	       matches	the  strings  ad,  abd	and  abcd, but not the
		       string abc.

       a*d*	       matches the strings ad, abcd, abcdef, aaaad and adddd.

       *a*d	       matches the strings ad, abcd, efabcd, aaaad and adddd.

   Patterns Used for Filename Expansion
       The rules described so far in Patterns Matching Multiple	Characters and
       Patterns	 Matching  a  Single  Character	are qualified by the following
       rules that apply	when pattern matching notation is  used	 for  filename

       1.  The slash character in a pathname must be explicitly	matched	by us-
	   ing 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
	   a[b/c]d  will not match such	pathnames as abd or a/d.  It will only
	   match a pathname of literally a[b/c]d.

       2.  If a	filename begins	with a period (.), the period must be  explic-
	   itly	 matched  by using a period as the first character of the pat-
	   tern	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:


	   a range expression, such as:


	   or a	character class	expression, such as:


	   It  is  unspecified whether an explicit period in a bracket expres-
	   sion	matching list, such as:


	   can match a leading period in a filename.

       3.  Specified patterns are matched against existing filenames and path-
	   names,   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:


	   search  permission  is needed for directories / and foo, search and
	   read	permissions are	needed for directory bar, and  search  permis-
	   sion	is needed for each x* 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 lo-
	   cale. If the	pattern	contains an invalid bracket expression or does
	   not	match  any existing filenames or pathnames, the	pattern	string
	   is left unchanged.

       find(1),	ksh(1),	fnmatch(3C), regex(5)

SunOS 5.10			  28 Mar 1995			    fnmatch(5)


Want to link to this manual page? Use this URL:

home | help