mirror of https://github.com/mkerrisk/man-pages
123 lines
4.7 KiB
Plaintext
123 lines
4.7 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "FNMATCH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" fnmatch
|
|
.SH NAME
|
|
fnmatch \- match a filename or a pathname
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <fnmatch.h>
|
|
.br
|
|
.sp
|
|
int fnmatch(const char *\fP\fIpattern\fP\fB, const char *\fP\fIstring\fP\fB,
|
|
int\fP \fIflags\fP\fB);
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIfnmatch\fP() function shall match patterns as described in
|
|
the Shell and Utilities volume of
|
|
IEEE\ Std\ 1003.1-2001, Section 2.13.1, Patterns Matching a Single
|
|
Character, and Section 2.13.2, Patterns Matching Multiple Characters.
|
|
It checks the string specified by the \fIstring\fP
|
|
argument to see if it matches the pattern specified by the \fIpattern\fP
|
|
argument.
|
|
.LP
|
|
The \fIflags\fP argument shall modify the interpretation of \fIpattern\fP
|
|
and \fIstring\fP. It is the bitwise-inclusive OR of
|
|
zero or more of the flags defined in \fI<fnmatch.h>\fP. If the FNM_PATHNAME
|
|
flag is
|
|
set in \fIflags\fP, then a slash character ( \fB'/'\fP ) in \fIstring\fP
|
|
shall be explicitly matched by a slash in
|
|
\fIpattern\fP; it shall not be matched by either the asterisk or question-mark
|
|
special characters, nor by a bracket expression. If
|
|
the FNM_PATHNAME flag is not set, the slash character shall be treated
|
|
as an ordinary character.
|
|
.LP
|
|
If FNM_NOESCAPE is not set in \fIflags\fP, a backslash character (
|
|
\fB'\\'\fP ) in \fIpattern\fP followed by any other
|
|
character shall match that second character in \fIstring\fP. In particular,
|
|
\fB"\\\\"\fP shall match a backslash in
|
|
\fIstring\fP. If FNM_NOESCAPE is set, a backslash character shall
|
|
be treated as an ordinary character.
|
|
.LP
|
|
If FNM_PERIOD is set in \fIflags\fP, then a leading period ( \fB'.'\fP
|
|
) in \fIstring\fP shall match a period in
|
|
\fIpattern\fP; as described by rule 2 in the Shell and Utilities volume
|
|
of IEEE\ Std\ 1003.1-2001, Section 2.13.3, Patterns Used for Filename
|
|
Expansion where the location of
|
|
"leading" is indicated by the value of FNM_PATHNAME:
|
|
.IP " *" 3
|
|
If FNM_PATHNAME is set, a period is "leading" if it is the first character
|
|
in \fIstring\fP or if it immediately follows a
|
|
slash.
|
|
.LP
|
|
.IP " *" 3
|
|
If FNM_PATHNAME is not set, a period is "leading" only if it is the
|
|
first character of \fIstring\fP.
|
|
.LP
|
|
.LP
|
|
If FNM_PERIOD is not set, then no special restrictions are placed
|
|
on matching a period.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
If \fIstring\fP matches the pattern specified by \fIpattern\fP, then
|
|
\fIfnmatch\fP() shall return 0. If there is no match,
|
|
\fIfnmatch\fP() shall return FNM_NOMATCH, which is defined in \fI<fnmatch.h>\fP.
|
|
If an error occurs, \fIfnmatch\fP() shall return another non-zero
|
|
value.
|
|
.SH ERRORS
|
|
.LP
|
|
No errors are defined.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.LP
|
|
None.
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
The \fIfnmatch\fP() function has two major uses. It could be used
|
|
by an application or utility that needs to read a directory
|
|
and apply a pattern against each entry. The \fIfind\fP utility is
|
|
an example of this. It can
|
|
also be used by the \fIpax\fP utility to process its \fIpattern\fP
|
|
operands, or by
|
|
applications that need to match strings in a similar manner.
|
|
.LP
|
|
The name \fIfnmatch\fP() is intended to imply \fIfilename\fP match,
|
|
rather than \fIpathname\fP match. The default action of
|
|
this function is to match filenames, rather than pathnames, since
|
|
it gives no special significance to the slash character. With the
|
|
FNM_PATHNAME flag, \fIfnmatch\fP() does match pathnames, but without
|
|
tilde expansion, parameter expansion, or special treatment
|
|
for a period at the beginning of a filename.
|
|
.SH RATIONALE
|
|
.LP
|
|
This function replaced the REG_FILENAME flag of \fIregcomp\fP() in
|
|
early proposals of
|
|
this volume of IEEE\ Std\ 1003.1-2001. It provides virtually the same
|
|
functionality as the \fIregcomp\fP() and \fIregexec\fP() functions
|
|
using the
|
|
REG_FILENAME and REG_FSLASH flags (the REG_FSLASH flag was proposed
|
|
for \fIregcomp\fP(),
|
|
and would have had the opposite effect from FNM_PATHNAME), but with
|
|
a simpler function and less system overhead.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIglob\fP() , \fIwordexp\fP() , the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, \fI<fnmatch.h>\fP, the Shell and Utilities
|
|
volume
|
|
of IEEE\ Std\ 1003.1-2001
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|