DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

fnmatch(S)


fnmatch -- find matching filename or pathname

Syntax

cc . . . -lc

#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:

No special restrictions are placed on matching a period if FNM_PERIOD is not set.

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:

Return values

Upon successful completion, fnmatch( ) returns zero if string matches the specified pattern; if there is no match, fnmatch( ) returns FNM_NOMATCH, a non-zero constant defined in <fnmatch.h>. If there is an error, fnmatch( ) returns some other non-zero value.

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

The return value FNM_BADPAT is SCO OpenServer specific and may not be supported in future releases. Its use without proper caution could make the application code non-XPG4 compliant.

See also

glob(S),
the XCU specification, Section 2.13, Patterning Matching Notation

Standards conformance

fnmatch(S) is conformant with:
X/Open CAE Specification, System Interfaces and Headers, Issue 4, 1992, with extensions that are maintained by The SCO Group.
© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003