fnmatch(S)

Syntax

#include <fnmatch.h>

int fnmatch(const char *pattern, const char *string, int flags);

Description

fnmatch(S) matches string against the filename pattern pattern and returns 0 if they match. The pattern argument is not a regular expression, but rather is in the form used in filename generation by the shell, like ``file*'', ``file[0-9]'', etc. See sh(C) for a brief summary of filename generation.

The flags argument is used to modify the interpretation of string and pattern, and is the bitwise inclusive OR of zero or more of the flags defined in <fnmatch.h>:

FNM_PATHNAME

Slash in string is matched explicitly by a slash in pattern.

FNM_NOESCAPE

Disable backslash escaping.

FNM_PERIOD

Leading period in string must be matched explicitly by a period in pattern.

If the flag FNM_PATHNAME is set, fnmatch( ) matches a slash character in string to a slash in pattern explicitly; it does not match a slash to an asterisk, a question mark, or a bracket expression. The default, when the flag FNM_PATHNAME is not set, is to treat the slash character as an ordinary character.

The flag FNM_NOESCAPE causes fnmatch( ) to treat a backslash (\) as an ordinary character. The default, when the flag FNM_NOESCAPE is not set, is to match a backslash character followed by any character in pattern only to that second character in string. In particular, the pattern "\\" will match a single backslash in string.

The flag FNM_PERIOD causes fnmatch( ) to match explicitly a leading period in string to a leading period in pattern. Here the meaning of ``leading'' depends on whether FNM_PATHNAME is set:

• If FNM_PATHNAME is not set, a ``leading period'' must be the first character.

• If FNM_PATHNAME is set in flags, a ``leading period'' can only be either the first character or the character immediately following a slash.

As an SCO OpenServer specific feature, fnmatch( ) also examines its pattern argument and returns FNM_BADPAT if it detects an invalid filename pattern. For example, the pattern [[:alpha]] will cause fnmatch( ) to return FNM_BADPAT because of the missing colon (:) after alpha. To use this feature and still return XPG4 compliance for an application program, conditionally include the code that detects FNM_BADPAT, as in

           switch (fnmatch (pattern, string, flags)) {
           case 0:
                   /* Code for match */
                   break;
           case FNM_NOMATCH:
                   /* Code for no match */
                   break;
           .
           .
           .
   #ifdef FNM_BADPAT
           case FNM_BADPAT:
                   /* Bad pattern error handling */
                   break;
   #endif /* FNM_BADPAT */
           .
           .
           .
           }

Filename pattern matching has been described in X/Open CAE Specification, Commands and Utilities, Issue 4, 1992 (XCU), Section 2.13.1, Patterns Matching a Single character, and Section 2.13.2, Patterns Matching Multiple Characters.

As the name implies, the primary purpose of fnmatch( ) is for filename match, rather than pathname match. No special significance is given to the slash character in the default mode. With the FNM_PATHNAME flag set, fnmatch( ) does match pathnames, but without tilde expansion, parameter expansion or any special treatment for period at the beginning of a filename.

fnmatch( ) has two major uses:

• use it in a utility like find(C), in order to read a directory and find matching entries for a pattern.

• use it in a utility like pax(C), in order to process its pattern operand.

Return values

As an SCO OpenServer specific feature, fnmatch( ) returns FNM_BADPAT if the filename pattern in pattern is invalid.

Diagnostics

The value of errno is undefined.

Warning

See also

Standards conformance