fnmatch Subroutine

Edit online

Purpose

Matches file name patterns.

Library

Standard C Library (libc. a)

Syntax

#include <fnmatch.h>
int fnmatch ( Pattern,  String,  Flags);
int Flags;
const char *Pattern, *String;

Description

The fnmatch subroutine checks the string specified by the String parameter to see if it matches the pattern specified by the Pattern parameter.

The fnmatch subroutine can be used by an application or command that needs to read a dictionary and apply a pattern against each entry; the findcommand is an example of this. It can also be used by the pax command to process its Pattern variables, or by applications that need to match strings in a similar manner.

Parameters

Item Description
Pattern Contains the pattern to which the String parameter is to be compared. The Pattern parameter can include the following special characters:
* (asterisk)
Matches zero, one, or more characters.
? (question mark)
Matches any single character, but will not match 0 (zero) characters.
[ ] (brackets)
Matches any one of the characters enclosed within the brackets. If a pair of characters separated by a dash are contained within the brackets, the pattern matches any character that lexically falls between the two characters in the current locale.
String Contains the string to be compared against the Pattern parameter.
Flags Contains a bit flag specifying the configurable attributes of the comparison to be performed by the fnmatch subroutine.

The Flags parameter modifies the interpretation of the Pattern and String parameters. It is the bitwise inclusive OR of zero or more of the following flags (defined in the fnmatch.h file):

FNM_PATHNAME
Indicates the / (slash) in the String parameter matches a / in the Pattern parameter.
FNM_PERIOD
Indicates a leading period in the String parameter matches a period in the Pattern parameter.
FNM_NOESCAPE
Enables quoting of special characters using the \ (backslash).

If the FNM_ PATHNAME flag is set in the Flags parameter, a / (slash) in the String parameter is explicitly matched by a / in the Pattern parameter. It is not matched by either the * (asterisk) or ? (question-mark) special characters, nor by a bracket expression. If the FNM_PATHNAME flag is not set, the / is treated as an ordinary character.

If the FNM_PERIOD flag is set in the Flags parameter, then a leading period in the String parameter only matches a period in the Pattern parameter; it is not matched by either the asterisk or question-mark special characters, nor by a bracket expression. The setting of the FNM_PATHNAME flag determines a period to be leading, according to the following rules:

  • If the FNM_PATHNAME flag is set, a . (period) is leading only if it is the first character in the String parameter or if it immediately follows a /.
  • If the FNM_PATHNAME flag is not set, a . (period) is leading only if it is the first character of the String parameter. If FNM_PERIOD is not set, no special restrictions are placed on matching a period.

If the FNM_NOESCAPE flag is not set in the Flags parameter, a \ (backslash) character in the Pattern parameter, followed by any other character, will match that second character in the String parameter. For example, \\ will match a backslash in the String parameter. If the FNM_NOESCAPE flag is set, a \ (backslash) will be treated as an ordinary character.

Return Values

If the value in the String parameter matches the pattern specified by the Pattern parameter, the fnmatch subroutine returns 0. If there is no match, the fnmatch subroutine returns the FNM_NOMATCH constant, which is defined in the fnmatch.h file. If an error occurs, the fnmatch subroutine returns a nonzero value.

Files

Item Description
/usr/include/fnmatch.h Contains system-defined flags and constants.