path: root/usr/src/man/man3c/fnmatch.3c

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions 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.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved
.\" Portions Copyright (c) 2002, Sun Microsystems, Inc.  All Rights Reserved
.\" Copyright 2017 Nexenta Systems, Inc.
.\"
.Dd August 14, 2017
.Dt FNMATCH 3C
.Os
.Sh NAME
.Nm fnmatch
.Nd match filename or path name
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In fnmatch.h
.Ft int
.Fo fnmatch
.Fa "const char *pattern"
.Fa "const char *string"
.Fa "int flags"
.Fc
.Sh DESCRIPTION
The
.Fn fnmatch
function matches patterns as described on the
.Xr fnmatch 5
manual page
.Po with the exceptions noted in the
.Sx STANDARDS
.Pc .
It checks the
.Fa string
argument to see if it matches the
.Fa pattern
argument.
.Pp
The
.Fa flags
argument modifies the interpretation of
.Fa pattern
and
.Fa string .
It is the bitwise inclusive OR of zero or more of the following flags defined in
the header
.In fnmatch.h .
.Bl -tag -width "FNM_LEADING_DIR"
.It Dv FNM_PATHNAME
If set, a slash
.Pq Qq /
character in
.Fa string
will be explicitly matched by a slash in
.Fa pattern ;
it will not be matched by either the asterisk
.Pq Qq *
or question-mark
.Pq Qq \&?
special characters, nor by a bracket
.Pq Qq []
expression.
.sp
If not set, the slash character is treated as an ordinary character.
.It Dv FNM_IGNORECASE
If set, the
.Fa string
will be transliterated to lower case before doing the actual match.
This transliteration is done using
.Xr towlower_l 3C ,
using the locale of the current thread.
If no locale is set, then the global locale is used instead.
.Pp
If not set, the match will use
.Fa string
with no changes, making the match case-sensitive.
.Pp
For compatibility with
.Fx
implementation of
.Fn fnmatch ,
header
.In fnmatch.h
provides the
.Dv FNM_FOLDCASE
flag having the same meaning.
.It Dv FNM_NOESCAPE
If not set, a backslash character
.Pq Qq \e
in
.Fa pattern
followed by any other character will match that second character in
.Fa string .
In particular,
.Qq \e\e
will match a backslash in
.Fa string .
.Pp
If set, a backslash character will be treated as an ordinary character.
.It Dv FNM_PERIOD
If set, a leading period in
.Fa string
will match a period in
.Fa pattern ;
where the location of
.Qq leading
is indicated by the value of
.Dv FNM_PATHNAME :
.Bl -bullet
.It
If
.Dv FNM_PATHNAME
is set, a period is
.Qq leading
if it is the first character in
.Fa string
or if it immediately follows a slash.
.It
If
.Dv FNM_PATHNAME
is not set, a period is
.Qq leading
only if it is the first character of
.Fa string .
.El
.Pp
If not set, no special restrictions are placed on matching a period.
.It Dv FNM_LEADING_DIR
Match if
.Fa pattern
matches initial segment of
.Fa string
which is followed by a slash.
.El
.Sh RETURN VALUES
If
.Fa string
matches the pattern specified by
.Fa pattern ,
then
.Fn fnmatch
returns 0.
If there is no match,
.Fn fnmatch
returns
.Dv FNM_NOMATCH ,
which is defined in the header
.In fnmatch.h .
If an error occurs,
.Fn fnmatch
returns another non-zero value.
.Sh USAGE
The
.Fn fnmatch
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
.Xr find 1
utility is an example of this.
It can also be used by the
.Xr pax 1
utility to process its
.Fa pattern
operands, or by applications that need to match strings in a similar manner.
.Pp
The name
.Fn fnmatch
is intended to imply
.Sy filename
match, rather than
.Sy pathname
match.
The default action of this function is to match filenames, rather than path
names, since it gives no special significance to the slash character.
With the
.Dv FNM_PATHNAME
flag,
.Fn fnmatch
does match path names, but without tilde expansion, parameter expansion, or
special treatment for period at the beginning of a filename.
.Sh CODE SET INDEPENDENCE
.Sy Enabled
.Sh INTERFACE STABILITY
.Sy Standard
.Sh MT-LEVEL
.Sy MT-Safe with exceptions
.Pp
The
.Fn fnmatch
function can be used safely in multithreaded applications, as long as
.Xr setlocale 3C
is not being called to change the locale.
.Sh SEE ALSO
.Xr find 1 ,
.Xr pax 1 ,
.Xr glob 3C ,
.Xr setlocale 3C ,
.Xr wordexp 3C ,
.Xr attributes 5 ,
.Xr fnmatch 5 ,
.Xr standards 5
.Sh STANDARDS
The current implementation of the
.Fn fnmatch
function
.Em does not
conform to
.St -p1003.2 .
Collating symbol expressions, equivalence class expressions and
character class expressions are not supported.
.Sh BUGS
The pattern
.Qq *
matches the empty string, even if
.Dv FNM_PATHNAME
is specified.