fnmatch()

Check to see if a file or path name matches a pattern

Synopsis:

#include <fnmatch.h>

int fnmatch( const char* pat, 
             const char* str, 
             int flags );

Arguments:

pat

The pattern to match; see “Pattern Matching Special Characters,” below.

str

The string to match against the pattern.

flags

Flags that modify interpretation of pat and str; a bitwise inclusive OR of these bits:

FNM_PATHNAME

If this is set, a slash character in str is explicitly matched by a slash in pat; it isn't matched by either the asterisk or question mark special characters, or by a bracket expression.

FNM_PERIOD

If this is set, a leading period in str matches a period in pat, where the definition of “leading” depends on FNM_PATHNAME:

• If FNM_PATHNAME is set, a period is leading if it's the first character in str, or if it immediately follows a slash.
• If FNM_PATHNAME isn't set, a period is leading only if it's the first character in str.

FNM_QUOTE

If this isn't set, a backslash (\) in pat followed by another character matches that second character. If FNM_QUOTE is set, a backslash is treated as an ordinary character.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The fnmatch() function checks the file or path name specified by the str argument to see if it matches the pattern specified by the pat argument.

Pattern Matching Special Characters

A pattern-matching special character that is quoted is a pattern that matches the special character itself. When not quoted, such special characters have special meaning in the specification of patterns. The pattern-matching special characters and the contexts in which they have their special meaning are as follows:

?

Matches any printable or nonprintable collating element except <newline>.

*

Matches any string, including the null string.

[bracket_expr]

Matches a single collating element as per Regular Expression Bracket Expressions (1003.2 2.9.1.2) except that:

• The exclamation point character (!) replaces the circumflex character (^) in its role as a nonmatching list in the regular expression notation.
• The backslash is used as an escape character within bracket expressions.

The ?, * and [ characters aren't special when used inside a bracket expression.

The concatenation of patterns matching a single character is a valid pattern that matches the concatenation of the single characters or collating elements matched by each of the concatenated patterns. For example, the pattern a[bc] matches the strings ab and ac.

The concatenation of one or more patterns matching a single character with one or more asterisks (*) is a valid pattern. In such patterns, each asterisk matches a string of zero or more characters, up to the first character that matches the character following the asterisk in the pattern. For example, the pattern a*d matches the strings ad, abd, and abcd, but not the string abc.

When an asterisk is the first or last character in a pattern, it matches zero or more characters that precede or follow the characters matched by the remainder of the pattern. For example, the pattern a*d* matches the strings ad, abcd, abcdef, aaaad and adddd; the pattern *a*d matches the strings ad, abcd, efabcd, aaaad and adddd.

Returns:

0

The str argument matches the pattern specified by pat.

Nonzero

The str argument doesn't match the pattern specified by pat.

Examples:

/*
 * The following example accepts a set of patterns
 * for filenames as argv[1..argc].  It reads lines
 * from standard input, and outputs the lines that
 * match any of the patterns.
 */
#include <stdio.h>
#include <fnmatch.h>
#include <stdlib.h>
#include <limits.h>

int main( int argc, char **argv )
  {
    int  i;
    char buffer[PATH_MAX+1];

    while( gets( buffer ) ) {
      for( i = 0; i < argc; i++ ) {
        if( fnmatch( argv[i], buffer, 0 ) == 0 ) {
          puts( buffer );
          break;
        }
      }
    }
    exit( EXIT_SUCCESS );
  }

Classification:

POSIX 1003.1

See also:

regcomp()