fnmatch.3p (5383B)
- '\" et
- .TH FNMATCH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- fnmatch
- \(em match a filename string or a pathname
- .SH SYNOPSIS
- .LP
- .nf
- #include <fnmatch.h>
- .P
- int fnmatch(const char *\fIpattern\fP, const char *\fIstring\fP, int \fIflags\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIfnmatch\fR()
- function shall match patterns as described in the Shell and Utilities volume of POSIX.1\(hy2017,
- .IR "Section 2.13.1" ", " "Patterns Matching a Single Character"
- and
- .IR "Section 2.13.2" ", " "Patterns Matching Multiple Characters".
- It checks the string specified by the
- .IR string
- argument to see if it matches the pattern specified by the
- .IR pattern
- argument.
- .P
- The
- .IR flags
- argument shall modify the interpretation of
- .IR pattern
- and
- .IR string .
- It is the bitwise-inclusive OR of zero or more of the flags defined in
- .IR <fnmatch.h> .
- If the FNM_PATHNAME flag is set in
- .IR flags ,
- then a
- <slash>
- character (\c
- .BR '/' )
- in
- .IR string
- shall be explicitly matched by a
- <slash>
- in
- .IR pattern ;
- 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.
- .P
- If FNM_NOESCAPE is not set in
- .IR flags ,
- a
- <backslash>
- character in
- .IR pattern
- followed by any other character shall match that second character in
- .IR string .
- In particular,
- .BR \(dq\e\e\(dq
- shall match a
- <backslash>
- in
- .IR string .
- If
- .IR pattern
- ends with an unescaped
- <backslash>,
- \fIfnmatch\fR()
- shall return a non-zero value (indicating either no match or an error).
- If FNM_NOESCAPE is set, a
- <backslash>
- character shall be treated as an ordinary character.
- .P
- If FNM_PERIOD is set in
- .IR flags ,
- then a leading
- <period>
- (\c
- .BR '.' )
- in
- .IR string
- shall match a
- <period>
- in
- .IR pattern ;
- as described by rule 2 in the Shell and Utilities volume of POSIX.1\(hy2017,
- .IR "Section 2.13.3" ", " "Patterns Used for Filename Expansion"
- where the location of ``leading'' is indicated by the value
- of FNM_PATHNAME:
- .IP " *" 4
- If FNM_PATHNAME is set, a
- <period>
- is ``leading'' if it is the first character in
- .IR string
- or if it immediately follows a
- <slash>.
- .IP " *" 4
- If FNM_PATHNAME is not set, a
- <period>
- is ``leading'' only if it is the first character of
- .IR string .
- .P
- If FNM_PERIOD is not set, then no special restrictions are placed on
- matching a period.
- .SH "RETURN VALUE"
- If
- .IR string
- matches the pattern specified by
- .IR pattern ,
- then
- \fIfnmatch\fR()
- shall return 0. If there is no match,
- \fIfnmatch\fR()
- shall return FNM_NOMATCH, which is defined in
- .IR <fnmatch.h> .
- If an error occurs,
- \fIfnmatch\fR()
- shall return another non-zero value.
- .SH ERRORS
- No errors are defined.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- None.
- .SH "APPLICATION USAGE"
- The
- \fIfnmatch\fR()
- 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
- .IR find
- utility is an example of this. It can also be used by the
- .IR pax
- utility to process its
- .IR pattern
- operands, or by applications that need to match strings in a similar
- manner.
- .P
- The name
- \fIfnmatch\fR()
- is intended to imply
- .IR "filename"
- match, rather than
- .IR "pathname"
- match. The default action of this function is to match filename strings,
- rather than pathnames, since it gives no special significance to the
- <slash>
- character. With the FNM_PATHNAME flag,
- \fIfnmatch\fR()
- does match pathnames, but without tilde expansion, parameter
- expansion, or special treatment for a
- <period>
- at the beginning of a filename.
- .SH RATIONALE
- This function replaced the REG_FILENAME flag of
- \fIregcomp\fR()
- in early proposals of this volume of POSIX.1\(hy2017. It provides virtually the same functionality
- as the
- \fIregcomp\fR()
- and
- \fIregexec\fR()
- functions using the REG_FILENAME and REG_FSLASH flags (the REG_FSLASH
- flag was proposed for
- \fIregcomp\fR(),
- and would have had the opposite effect from FNM_PATHNAME), but with a
- simpler function and less system overhead.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIglob\fR\^(\|)",
- .IR "Section 2.6" ", " "Word Expansions"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<fnmatch.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 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 .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .