fnmatch, fnmatch-gnu: Document known bugs

[Bruno Haible]

With the new unit tests for fnmatch(), I see test failures on several platforms.
(Did anybody expect something else?)

This patch documents the problems. The next patches will then go on to actually
fix the problems.


2023-07-23  Bruno Haible  <bruno@clisp.org>

        fnmatch, fnmatch-gnu: Document known bugs.
        * doc/posix-headers/fnmatch.texi: Mention the macros FNM_LEADING_DIR,
        FNM_CASEFOLD, FNM_EXTMATCH, FNM_FILE_NAME.
        * doc/posix-functions/fnmatch.texi: Reference the glibc documentation
        and the Linux man page. Document the effects of the two modules and all
        the known bugs in detail.

diff --git a/doc/posix-headers/fnmatch.texi b/doc/posix-headers/fnmatch.texi
index 8e59b764f0..175f5f9886 100644
--- a/doc/posix-headers/fnmatch.texi
+++ b/doc/posix-headers/fnmatch.texi
@@ -3,15 +3,29 @@
 
 POSIX specification:@* 
@url{https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/fnmatch.h.html}
 
-Gnulib module: fnmatch-h
+Gnulib module: fnmatch-h, fnmatch-gnu
 
-Portability problems fixed by Gnulib:
+Portability problems fixed by Gnulib module @code{fnmatch-h}:
 @itemize
 @item
 This header file is missing on some platforms:
 mingw, MSVC 14.
 @end itemize
 
+Portability problems fixed by Gnulib module @code{fnmatch-gnu}, together with 
module @code{fnmatch-h}:
+@itemize
+@item
+The macros @code{FNM_LEADING_DIR} and @code{FNM_CASEFOLD} are not defined
+on some platforms:
+AIX 7.2, HP-UX 11.31, IRIX 6.5, Solaris 10.
+@item
+The macro @code{FNM_EXTMATCH} is not defined on all non-glibc platforms:
+musl libc, macOS 12.5, FreeBSD 13.2, NetBSD 9.3, OpenBSD 7.2, Minix 3.3, AIX 
7.2, HP-UX 11.31, IRIX 6.5, Solaris 11.4, Cygwin 3.4.6, Android 13.
+@item
+The macro @code{FNM_FILE_NAME} is not defined on some platforms:
+NetBSD 9.3, AIX 7.2, HP-UX 11.31, IRIX 6.5, Solaris 10.
+@end itemize
+
 Portability problems not fixed by Gnulib:
 @itemize
 @end itemize
diff --git a/doc/posix-functions/fnmatch.texi b/doc/posix-functions/fnmatch.texi
index 0e239f6c65..3211cc892a 100644
--- a/doc/posix-functions/fnmatch.texi
+++ b/doc/posix-functions/fnmatch.texi
@@ -6,18 +6,192 @@
 
 LSB specification:@* 
@url{https://refspecs.linuxbase.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/baselib-fnmatch-3.html}
 
+Documentation:
+@itemize
+@item
+@ifinfo
+@ref{Wildcard Matching,,Wildcard Matching,libc},
+@end ifinfo
+@ifnotinfo
+@url{https://www.gnu.org/software/libc/manual/html_node/Wildcard-Matching.html},
+@end ifnotinfo
+@item
+@uref{https://www.kernel.org/doc/man-pages/online/pages/man3/fnmatch.3.html,,man
 fnmatch}.
+@end itemize
+
 Gnulib module: fnmatch or fnmatch-gnu
 
-Portability problems fixed by Gnulib:
+Portability problems fixed by either Gnulib module @code{fnmatch} or 
@code{fnmatch-gnu}:
 @itemize
 @item
 This function is missing on some platforms:
 mingw, MSVC 14.
 @item
-This function is broken on some platforms:
-some versions of glibc, NetBSD 7.1, some versions of Solaris.
+Ranges that start or end with a backslash don't work right on some platforms:
+@c https://sourceware.org/bugzilla/show_bug.cgi?id=361
+glibc 2.3.3.
+@item
+In the pattern, an opening bracket without closing bracket does not match
+a literal @code{'['} on some platforms:
+@c https://sourceware.org/bugzilla/show_bug.cgi?id=12378
+@c Failing test cases:
+@c fnmatch ("[[:alpha:]'[:alpha:]\0]", "a", 0) == FNM_NOMATCH
+@c fnmatch ("[a[.\0.]]", "a", 0) == FNM_NOMATCH
+@c fnmatch ("[", "[", 0) == 0
+@c fnmatch ("[/b", "[/b", 0) == 0
+glibc 2.12,
+@c Failing test cases:
+@c fnmatch ("[[:alpha:]'[:alpha:]\0]", "a", 0) == FNM_NOMATCH
+@c fnmatch ("[a[.\0.]]", "a", 0) == FNM_NOMATCH
+@c fnmatch ("[", "[", 0) == 0
+@c fnmatch ("[", "]", 0) == FNM_NOMATCH
+@c fnmatch ("[/b", "[/b", 0) == 0
+macOS 12.5.
+@end itemize
+
+Portability problems fixed by Gnulib module @code{fnmatch-gnu}:
+@itemize
+@item
+This function does not support the flags @code{FNM_LEADING_DIR} and
+@code{FNM_CASEFOLD} on some platforms:
+AIX 7.2, HP-UX 11.31, IRIX 6.5, Solaris 10.
+@item
+The flag @code{FNM_CASEFOLD} does not work in many situations on some 
platforms:
+@c Failing test cases:
+@c fnmatch ("H\366hle", "H\326hLe", FNM_CASEFOLD) == 0
+@c etc.
+@c fnmatch ("\303\266zg\303\274r", "\303\226ZG\303\234R", FNM_CASEFOLD) == 0
+@c etc.
+@c fnmatch ("xy", "Xy", FNM_CASEFOLD) == 0
+@c etc.
+@c fnmatch ("\201\060\213\062zg\250\271r", 
"\201\060\211\060ZG\201\060\211\065R", FNM_CASEFOLD) == 0
+@c etc.
+NetBSD 9.3.
+@item
+The flag @code{FNM_CASEFOLD} does not work for multibyte characters
+consisting of more than one byte on some platforms:
+@c Failing test cases:
+@c fnmatch ("\303\266zg\303\274r", "\303\226ZG\303\234R", FNM_CASEFOLD) == 0
+@c etc.
+Android 13.
+@item
+This function does not support the flag @code{FNM_EXTMATCH}
+on all non-glibc platforms:
+musl libc, macOS 12.5, FreeBSD 13.2, NetBSD 9.3, OpenBSD 7.2, Minix 3.3, AIX 
7.2, HP-UX 11.31, IRIX 6.5, Solaris 11.4, Cygwin 3.4.6, Android 13.
+@item
+This function does not support the flag @code{FNM_FILE_NAME} as an
+alias of @code{FNM_PATHNAME} on some platforms:
+NetBSD 9.3, AIX 7.2, HP-UX 11.31, IRIX 6.5, Solaris 10.
 @end itemize
 
 Portability problems not fixed by Gnulib:
 @itemize
+@item
+The @code{"?"} pattern character fails to match characters outside the
+single-byte range on some platforms:
+@c Failing test cases:
+@c fnmatch ("x?y", "x\303\274y", 0) == 0
+@c fnmatch ("x?y", "x\303\237y", 0) == 0
+@c fnmatch ("x?y", "x\360\237\230\213y", 0) == 0
+@c fnmatch ("x?y", "x\306\374y", 0) == 0
+@c fnmatch ("x?y", "x\313\334y", 0) == 0
+@c fnmatch ("x?y", "x\270\354y", 0) == 0
+@c fnmatch ("x?y", "x\250\271y", 0) == 0
+@c fnmatch ("x?y", "x\201\060\211\070y", 0) == 0
+@c fnmatch ("x?y", "x\224\071\375\067y", 0) == 0
+NetBSD 9.3,
+@c Failing test cases:
+@c fnmatch ("x?y", "x\303\274y", 0) == 0
+@c fnmatch ("x?y", "x\303\237y", 0) == 0
+@c fnmatch ("x?y", "x\360\237\230\213y", 0) == 0
+Android 13.
+@item
+The @code{"?"} pattern character fails to match characters outside the
+Unicode BMP on some platforms:
+@c Failing test cases:
+@c fnmatch ("x?y", "x\360\237\230\213y", 0) == 0
+Solaris 10, Cygwin 3.4.6,
+@c Failing test cases:
+@c fnmatch ("x?y", "x\360\237\230\213y", 0) == 0
+@c fnmatch ("x[[:alnum:]]y", "x\360\220\214\260y", 0) == 0
+@c fnmatch ("x[[:alpha:]]y", "x\360\220\214\260y", 0) == 0
+@c fnmatch ("x[[:graph:]]y", "x\360\240\200\200y", 0) == 0
+@c fnmatch ("x[[:lower:]]y", "x\360\220\221\201y", 0) == 0
+@c fnmatch ("x[[:print:]]y", "x\360\240\200\200y", 0) == 0
+@c fnmatch ("x[[:punct:]]y", "x\360\235\204\200y", 0) == 0
+@c fnmatch ("x[[:upper:]]y", "x\360\220\220\231y", 0) == 0
+MSVC,
+@c Failing test cases:
+@c fnmatch ("x?y", "x\360\237\230\213y", 0) == 0
+@c fnmatch ("x[[:alnum:]]y", "x\360\220\214\260y", 0) == 0
+@c fnmatch ("x[[:alpha:]]y", "x\360\220\214\260y", 0) == 0
+@c fnmatch ("x[[:graph:]]y", "x\360\240\200\200y", 0) == 0
+@c fnmatch ("x[[:lower:]]y", "x\360\220\221\201y", 0) == 0
+@c fnmatch ("x[[:print:]]y", "x\360\240\200\200y", 0) == 0
+@c fnmatch ("x[[:upper:]]y", "x\360\220\220\231y", 0) == 0
+32-bit AIX.
+@item
+In the pattern, negated character ranges (such as @code{[!a-z]}) are not
+supported on some platforms:
+@c Failing test cases:
+@c fnmatch ("[!a-z]", "", 0) == FNM_NOMATCH
+Solaris 11.4.
+@item
+In the pattern, character classes (such as @code{[:alnum:]}) inside
+bracket expressions are not supported on some platforms:
+@c Failing test cases:
+@c fnmatch ("[[:alnum:]]", "a", 0) == 0
+@c etc.
+FreeBSD 13.2, NetBSD 9.3, Cygwin 2.9.0.
+@item
+In the pattern, character classes (such as @code{[:alnum:]}) inside
+bracket expressions fail to match characters outside the single-byte
+range on some platforms:
+@c Failing test cases:
+@c fnmatch ("x[[:alnum:]]y", "x\305\201y", 0) == 0
+@c fnmatch ("x[[:alnum:]]y", "x\360\220\214\260y", 0) == 0
+@c fnmatch ("x[[:alpha:]]y", "x\305\201y", 0) == 0
+@c fnmatch ("x[[:alpha:]]y", "x\360\220\214\260y", 0) == 0
+@c fnmatch ("x[[:graph:]]y", "x\302\270y", 0) == 0
+@c fnmatch ("x[[:graph:]]y", "x\360\240\200\200y", 0) == 0
+@c fnmatch ("x[[:lower:]]y", "x\303\277y", 0) == 0
+@c fnmatch ("x[[:lower:]]y", "x\360\220\221\201y", 0) == 0
+@c fnmatch ("x[[:print:]]y", "x\302\270y", 0) == 0
+@c fnmatch ("x[[:print:]]y", "x\360\240\200\200y", 0) == 0
+@c fnmatch ("x[[:punct:]]y", "x\302\277y", 0) == 0
+@c fnmatch ("x[[:space:]]y", "x\343\200\200y", 0) == 0
+@c fnmatch ("x[[:upper:]]y", "x\320\251y", 0) == 0
+@c fnmatch ("x[[:upper:]]y", "x\360\220\220\231y", 0) == 0
+Android 13.
+@item
+The character class @code{[:cntrl:]} matches the empty string
+on some platforms:
+@c Failing test cases:
+@c fnmatch ("[[:cntrl:]]", "", 0) == FNM_NOMATCH
+Solaris 11.4.
+@item
+In the pattern, an opening bracket without closing bracket does not match
+a literal @code{'['} on some platforms:
+@c Failing test cases:
+@c fnmatch ("[", "[", 0) == 0
+@c fnmatch ("[/-/]", "/", 0) == 0
+NetBSD 9.3.
+@end itemize
+
+Note: Gnulib's replacement function has some limitations:
+@itemize
+@item
+It does not implement patterns with
+collating elements (such as @code{"[[.ch.]]"}) or
+equivalence classes (such as @code{"[[=a=]]"}).
+@item
+In the pattern, the character class @code{[:blank:]} inside bracket
+expressions is not supported on some platforms:
+@c Failing test cases:
+@c fnmatch ("[[:blank:]]", " ", 0) == 0
+mingw.
+@c Additionally, on mingw 10, there are test failures:
+@c fnmatch ("x?y", "x\223\372y", 0) == 0
+@c fnmatch ("x?y", "x\244\351y", 0) == 0
+@c fnmatch ("x?y", "x\310\325y", 0) == 0
 @end itemize