Technical Reference: Base Operating System and Extensions, Volume 1

fnmatch Subroutine

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 find command 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

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).
FNM_IGNORECASE: Ignores uppercase and lowercase when matching alphabetic characters (available only in AIX 5.1 or later).

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

/usr/include/fnmatch.h

Contains system-defined flags and constants.

Related Information

The glob (glob Subroutine) subroutine, globfree (globfree Subroutine) subroutine, regcomp subroutine, regfree subroutine, regerror subroutine, regexec subroutine.

The find command, pax command.

Files, Directories, and File Systems for Programmers and Understanding Internationalized Regular Expression Subroutines Ln AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs