fnmatch()

check to see if a string matches a pattern

Synopsis:

#include <fnmatch.h>
int fnmatch( const char *pat, 
             const char *str, 
             int flag );

Description:

The fnmatch() function checks the string specified by the str argument to see if it matches the pattern specified by the pat argument.

The flag argument is a bitwise inclusive OR of the bits described below. It modifies the interpretation of pat and str.

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_NOESCAPE

If this is set, it disables backslash escaping:

• If FNM_NOESCAPE isn't set in flags, a backslash character (\) in pat followed by any other character matches that second character in str. In particular, \\ matches a backslash in str.
• If FNM_NOESCAPE is set, a backslash character is treated as an ordinary character.

FNM_QUOTE (QNX extension)

This flag is the reverse of FNM_NOESCAPE:

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

FNM_QUOTE is included for backward compatibility - use FNM_NOESCAPE instead.

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:

?

a ? is a pattern that matches any printable or nonprintable collating element except <newline>.

*

the * matches any string, including the null string.

[bracket_expr]

a pattern that 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

str matches the pattern specified by pat

Nonzero

str 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;
        }
      }
    }
    return( EXIT_SUCCESS );
  }

Classification:

POSIX 1003.2

Caveats:

FNM_QUOTE is a QNX extension, and is intended for backward compatibility. Use FNM_NOESCAPE instead.

See also:

regcomp()