fnmatch(), _fnmatchv()

Updated: May 06, 2022

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 );

int _fnmatchv( const char *pat,
               const struct iovec *iov,
               unsigned iovnum,
               int flags );

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 Neutrino 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.

(QNX Neutrino 7.0 or later) The _fnmatchv() function is a QNX Neutrino 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 Neutrino

Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes