fnmatch(), _fnmatchv()

Arguments:

pat

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

str

(fnmatch() only) The string to match against the pattern.

iov

(_fnmatchv() only) The string, specified as an I/O vector, to match against the pattern. For more information, see the entry for SETIOV().

iovnum

(_fnmatchv() only) The number of entries in the I/O vector, iov.

flags

Flags that modify interpretation of the file or path name; a bitwise inclusive OR of zero or more of these bits:

FNM_CASEFOLD

(BSD extension) Ignore case when matching names.

FNM_LEADING_DIR

(GNU extension) Ignore a trailing sequence of characters starting with a slash in the string; that is, test whether the string starts with a directory name that pat matches.

FNM_NOESCAPE

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

FNM_PATHNAME

If this is set, a slash character in the string 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 the string 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 the string, 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 the string.

FNM_QUOTE

(QNX OS extension) The same as FNM_NOESCAPE.

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.

The _fnmatchv() function is a QNX OS extension that's similar to fnmatch(), but the file or path name is specified as an I/O vector.

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 string matches the pattern specified by pat.

Nonzero

The string 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];

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

Classification:

fnmatch() is POSIX 1003.1; _fnmatchv() is QNX OS