8578 sync fnmatch(3C) with upstream

Reviewed by: Toomas Soome <toomas@me.com>
Reviewed by: C Fraire <cfraire@me.com>
Approved by: Dan McDonald <danmcd@joyent.com>

1 files changed, 252 insertions, 143 deletions

diff --git a/usr/src/man/man3c/fnmatch.3c b/usr/src/man/man3c/fnmatch.3c
index 8b93c593b4..c2e82e6b99 100644
--- a/usr/src/man/man3c/fnmatch.3c
+++ b/usr/src/man/man3c/fnmatch.3c
@@ -1,148 +1,257 @@
-'\" te
-.\"  Copyright (c) 1992, X/Open Company Limited All Rights Reserved  Portions Copyright (c) 2002, Sun Microsystems, Inc.  All Rights Reserved
-.\" 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
+.\"
+.\" 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 Sun OS 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]
-.TH FNMATCH 3C "Jun 11, 2015"
-.SH NAME
-fnmatch \- match filename or path name
-.SH SYNOPSIS
-.LP
-.nf
-#include <fnmatch.h>
-
-\fBint\fR \fBfnmatch\fR(\fBconst char *\fR\fIpattern\fR, \fBconst char *\fR\fIstring\fR, \fBint\fR \fIflags\fR);
-.fi
-
-.SH DESCRIPTION
-.LP
-The \fBfnmatch()\fR function matches patterns as described on the
-\fBfnmatch\fR(5) manual page.  It checks the \fIstring\fR argument to see if it
-matches the \fIpattern\fR argument.
-.sp
-.LP
-The \fIflags\fR argument modifies the interpretation of \fIpattern\fR and
-\fIstring\fR. It is the bitwise inclusive \fBOR\fR of zero or more of the
-following flags defined in the header <\fBfnmatch.h\fR>.
-.sp
-.ne 2
-.na
-\fB\fBFNM_PATHNAME\fR  \fR
-.ad
-.RS 18n
-If set, a slash (\fB/\fR) character in \fIstring\fR will be explicitly matched
-by a slash in \fIpattern\fR; it will not be matched by either the asterisk
-(\fB*\fR) or question-mark (\fB?\fR) special characters, nor by a bracket
-(\fB[\|]\fR) expression.
+.\"
+.\" 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
+.\" Sun OS 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.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBFNM_IGNORECASE\fR\fR
-.ad
-.RS 18n
-If set, the \fIstring\fR will be transliterated to lower case before doing the
-actual match. This transliteration is done using \fBtowlower_l\fR(3C), using
-the locale of the current thread. If no locale is set, then the global locale
-is used instead.
-.sp
-If not set, the match will use \fIstring\fR with no changes, making the match
-case-sensitive.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBFNM_NOESCAPE\fR\fR
-.ad
-.RS 18n
-If not set, a backslash character (\fB\e\fR) in \fIpattern\fR followed by any
-other character will match that second character in \fIstring\fR. In
-particular, "\fB\e\e\fR" will match a backslash in \fIstring\fR.
-.sp
+.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.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBFNM_PERIOD\fR\fR
-.ad
-.RS 18n
-If set, a leading period in \fIstring\fR will match a period in \fIpattern\fR;
-where the location of "leading" is indicated by the value of
-\fBFNM_PATHNAME\fR:
-.RS +4
-.TP
-.ie t \(bu
-.el o
-If \fBFNM_PATHNAME\fR is set, a period is "leading" if it is the first
-character in \fIstring\fR or if it immediately follows a slash.
-.RE
-.RS +4
-.TP
-.ie t \(bu
-.el o
-If \fBFNM_PATHNAME\fR is not set, a period is "leading" only if it is the first
-character of \fIstring\fR.
-.RE
-.RE
-
-.sp
-.RS 18n
+.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.
-.SH RETURN VALUES
-.LP
-If \fIstring\fR matches the pattern specified by \fIpattern\fR, then
-\fBfnmatch()\fR returns \fB0\fR. If there is no match, \fBfnmatch()\fR returns
-\fBFNM_NOMATCH\fR, which is defined in the header <\fBfnmatch.h\fR>. If an
-error occurs, \fBfnmatch()\fR returns another non-zero value.
-.SH USAGE
-.LP
-The \fBfnmatch()\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 \fBfind\fR(1) utility is an example of this. It can
-also be used by the \fBpax\fR(1) utility to process its \fIpattern\fR operands,
-or by applications that need to match strings in a similar manner.
-.sp
-.LP
-The name \fBfnmatch()\fR is intended to imply \fIfilename\fR match, rather than
-\fIpathname\fR 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 \fBFNM_PATHNAME\fR flag, \fBfnmatch()\fR does
-match path names, but without tilde expansion, parameter expansion, or special
-treatment for period at the beginning of a filename.
-.sp
-.LP
-The \fBfnmatch()\fR function can be used safely in multithreaded applications,
-as long as \fBsetlocale\fR(3C) is not being called to change the locale.
-.SH ATTRIBUTES
-.LP
-See \fBattributes\fR(5) for descriptions of the following attributes:
-.sp
-
-.sp
-.TS
-box;
-c | c
-l | l .
-ATTRIBUTE TYPE	ATTRIBUTE VALUE
-_
-CSI	Enabled
-_
-Interface Stability	Standard
-_
-MT-Level	MT-Safe with exceptions
-.TE
-
-.SH SEE ALSO
-.LP
-\fBfind\fR(1), \fBpax\fR(1), \fBglob\fR(3C), \fBsetlocale\fR(3C),
-\fBwordexp\fR(3C), \fBattributes\fR(5), \fBfnmatch\fR(5), \fBstandards\fR(5)
+.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.