Update documentation of AC_USE_SYSTEM_EXTENSIONS.

The list of macros documented as being defined by
AC_USE_SYSTEM_EXTENSIONS had gotten out of sync with the actual list.
Update it thoroughly.

Also, I introduced an error into the commentary when I merged Julien
ÉLIE’s patch to define _NETBSD_SOURCE and _OPENBSD_SOURCE in
AC_USE_SYSTEM_EXTENSIONS.  _OPENBSD_SOURCE does something on NetBSD
and *doesn’t* do anything on OpenBSD.  This is corrected.

Clean up the code in AC_USE_SYSTEM_EXTENSIONS a bit while I’m in
there; we now had a redundant definition of _NETBSD_SOURCE (one
unconditional and one conditional on minix/config.h existing).
Reorganize the macro to make it easier to catch problems like this in
the future.

* lib/autoconf/specific.m4 (AC_USE_SYSTEM_EXTENSIONS): Reorganize;
  remove redundant AC_DEFINE of _NETBSD_SOURCE; add some missing
  AC_BEFOREs; use _AC_CHECK_HEADER_ONCE for header checks;
  revise all commentary.
* doc/autoconf.texi (AC_USE_SYSTEM_EXTENSIONS): Update.

2 files changed, 111 insertions, 72 deletions

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 2df1e475..a67cccb2 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -8920,44 +8920,31 @@ disable the extensions, typically due to standards-conformance namespace
 issues.  This should be called before any macros that run the C
 compiler.  Also, when using this macro in concert with
 @code{AC_CONFIG_HEADERS}, be sure that @file{config.h} is included
-before any system header.  The following preprocessor macros are defined
-where appropriate:
+before any system header.
+
+The following preprocessor macros are defined unconditionally:
 
 @table @code
-@item _GNU_SOURCE
-@cvindex _GNU_SOURCE
-Enable extensions on GNU/Linux.
 @item _ALL_SOURCE
 @cvindex _ALL_SOURCE
-Enable extensions for AIX 3, and for Interix.
+Enable extensions on AIX 3 and Interix.
 @item _DARWIN_C_SOURCE
 @cvindex _DARWIN_C_SOURCE
-Enable extensions for macOS.
-@item _MINIX
-@cvindex _MINIX
-Identify Minix platform.  This particular preprocessor macro is
-obsolescent, and may be removed in a future release of Autoconf.
+Enable extensions on macOS.
+@item _GNU_SOURCE
+@cvindex _GNU_SOURCE
+Enable extensions on GNU systems.
 @item _NETBSD_SOURCE
 @cvindex _NETBSD_SOURCE
-Enable NetBSD-related extensions for Minix.
-@item _POSIX_1_SOURCE
-@cvindex _POSIX_1_SOURCE
-Enable additional Posix functions for Minix.
+Enable general extensions on NetBSD.
+Enable NetBSD compatibility extensions on Minix.
+@item _OPENBSD_SOURCE
+@cvindex _OPENBSD_SOURCE
+Enable OpenBSD compatibility extensions on NetBSD.
+Oddly enough, this does nothing on OpenBSD.
 @item _POSIX_PTHREAD_SEMANTICS
 @cvindex _POSIX_PTHREAD_SEMANTICS
-Enable threading extensions on Solaris.
-@item _POSIX_SOURCE
-@cvindex _POSIX_SOURCE
-Enable Posix functions for Minix.
-@item _TANDEM_SOURCE
-@cvindex _TANDEM_SOURCE
-Enable extensions for the HP NonStop platform.
-@item _XOPEN_SOURCE
-@cvindex _XOPEN_SOURCE
-Enable X/Open extensions for HP-UX.
-@item __EXTENSIONS__
-@cvindex __EXTENSIONS__
-Enable general extensions on Solaris.
+Enable Posix-compatible threading on Solaris.
 @item __STDC_WANT_IEC_60559_ATTRIBS_EXT__
 @cvindex __STDC_WANT_IEC_60559_ATTRIBS_EXT__
 Enable extensions specified by ISO/IEC TS 18661-5:2014.
@@ -8979,6 +8966,38 @@ Enable extensions specified by ISO/IEC TR 24731-2:2010.
 @item __STDC_WANT_MATH_SPEC_FUNCS__
 @cvindex __STDC_WANT_MATH_SPEC_FUNCS__
 Enable extensions specified by ISO/IEC 24747:2009.
+@item _TANDEM_SOURCE
+@cvindex _TANDEM_SOURCE
+Enable extensions on HP NonStop systems.
+@end table
+
+The following preprocessor macros are defined only when necessary;
+they enable access to extensions on some operating systems but
+@emph{disable} extensions on other operating systems.
+
+@table @code
+@item __EXTENSIONS__
+@cvindex __EXTENSIONS__
+Enable general extensions on Solaris.  This macro is defined only if
+the headers included by @code{AC_INCLUDES_DEFAULT}
+(@pxref{Default Includes}) work correctly with it defined.
+
+@item _MINIX
+@itemx _POSIX_SOURCE
+@itemx _POSIX_1_SOURCE
+@cvindex _MINIX
+@cvindex _POSIX_SOURCE
+@cvindex _POSIX_1_SOURCE
+Defined only on MINIX.  @code{_POSIX_SOURCE} and @code{_POSIX_1_SOURCE}
+are needed to enable a number of POSIX features on this OS.
+@code{_MINIX} does not affect the system headers' behavior;
+future versions of Autoconf may stop defining it.
+Programs that need to recognize Minix should use @code{AC_CANONICAL_HOST}.
+
+@item _XOPEN_SOURCE
+@cvindex _XOPEN_SOURCE
+Defined (with value 500) only if needed to make @file{wchar.h} declare
+@code{mbstate_t}.  This is known to be necessary on some versions of HP/UX.
 @end table
 
 @cvindex __STDC_WANT_DEC_FP__
diff --git a/lib/autoconf/specific.m4 b/lib/autoconf/specific.m4
index c209c646..275938ca 100644
--- a/lib/autoconf/specific.m4
+++ b/lib/autoconf/specific.m4
@@ -358,34 +358,21 @@ matches *mingw32*])# AC_MINGW32
 # ------------------------
 # Enable extensions on systems that normally disable them,
 # typically due to standards-conformance issues.
-#
-# Remember that #undef in AH_VERBATIM gets replaced with #define by
-# AC_DEFINE.  The goal here is to define all known feature-enabling
-# macros, then, if reports of conflicts are made, disable macros that
-# cause problems on some platforms (such as __EXTENSIONS__).
+# We unconditionally define as many of the known feature-enabling
+# as possible, reserving conditional behavior for macros that are
+# known to cause problems on some platforms (such as __EXTENSIONS__).
 AC_DEFUN_ONCE([AC_USE_SYSTEM_EXTENSIONS],
-[AC_BEFORE([$0], [AC_COMPILE_IFELSE])dnl
+[AC_BEFORE([$0], [AC_PREPROC_IFELSE])dnl
+AC_BEFORE([$0], [AC_COMPILE_IFELSE])dnl
+AC_BEFORE([$0], [AC_LINK_IFELSE])dnl
 AC_BEFORE([$0], [AC_RUN_IFELSE])dnl
-
-  AC_CHECK_HEADER([minix/config.h], [MINIX=yes], [MINIX=])
-  if test "$MINIX" = yes; then
-    AC_DEFINE([_POSIX_SOURCE], [1],
-      [Define to 1 if you need to in order for 'stat' and other
-       things to work.])
-    AC_DEFINE([_POSIX_1_SOURCE], [2],
-      [Define to 2 if the system does not provide POSIX.1 features
-       except with this defined.])
-    AC_DEFINE([_MINIX], [1],
-      [Define to 1 if on MINIX.])
-    AC_DEFINE([_NETBSD_SOURCE], [1],
-      [Define to 1 to make NetBSD features available.  MINIX 3 needs this.])
-  fi
-
+AC_BEFORE([$0], [AC_CHECK_INCLUDES_DEFAULT])dnl
+dnl #undef in AH_VERBATIM gets replaced with #define by AC_DEFINE.
 dnl Use a different key than __EXTENSIONS__, as that name broke existing
 dnl configure.ac when using autoheader 2.62.
 dnl The macros below are in alphabetical order ignoring leading _ or __
 dnl prefixes.
-  AH_VERBATIM([USE_SYSTEM_EXTENSIONS],
+AH_VERBATIM([USE_SYSTEM_EXTENSIONS],
 [/* Enable extensions on AIX 3, Interix.  */
 #ifndef _ALL_SOURCE
 # undef _ALL_SOURCE
@@ -394,9 +381,6 @@ dnl prefixes.
 #ifndef _DARWIN_C_SOURCE
 # undef _DARWIN_C_SOURCE
 #endif
-/* DragonflyBSD and FreeBSD's headers enable extensions by default;
-   extensions can be turned off by requesting a strict ISO C or POSIX
-   environment, but there is no way to explicitly turn them on. */
 /* Enable general extensions on Solaris.  */
 #ifndef __EXTENSIONS__
 # undef __EXTENSIONS__
@@ -405,15 +389,31 @@ dnl prefixes.
 #ifndef _GNU_SOURCE
 # undef _GNU_SOURCE
 #endif
-/* Enable NetBSD extensions on NetBSD.  */
+/* Identify the host operating system as Minix.
+   This macro does not affect the system headers' behavior.
+   A future release of Autoconf may stop defining this macro.  */
+#ifndef _MINIX
+# undef _MINIX
+#endif
+/* Enable general extensions on NetBSD.
+   Enable NetBSD compatibility extensions on Minix.  */
 #ifndef _NETBSD_SOURCE
 # undef _NETBSD_SOURCE
 #endif
-/* Enable OpenBSD extensions on OpenBSD.  */
+/* Enable OpenBSD compatibility extensions on NetBSD.
+   Oddly enough, this does nothing on OpenBSD.  */
 #ifndef _OPENBSD_SOURCE
 # undef _OPENBSD_SOURCE
 #endif
-/* Enable threading extensions on Solaris.  */
+/* Define to 1 if needed for POSIX-compatible behavior.  */
+#ifndef _POSIX_SOURCE
+# undef _POSIX_SOURCE
+#endif
+/* Define to 2 if needed for POSIX-compatible behavior.  */
+#ifndef _POSIX_1_SOURCE
+# undef _POSIX_1_SOURCE
+#endif
+/* Enable POSIX-compatible threading on Solaris.  */
 #ifndef _POSIX_PTHREAD_SEMANTICS
 # undef _POSIX_PTHREAD_SEMANTICS
 #endif
@@ -449,13 +449,19 @@ dnl prefixes.
 #ifndef _TANDEM_SOURCE
 # undef _TANDEM_SOURCE
 #endif
-/* Enable X/Open extensions if necessary.  HP-UX 11.11 defines
-   mbstate_t only if _XOPEN_SOURCE is defined to 500, regardless of
-   whether compiling with -Ae or -D_HPUX_SOURCE=1.  */
+/* Enable X/Open extensions.  Define to 500 only if necessary
+   to make mbstate_t available.  */
 #ifndef _XOPEN_SOURCE
 # undef _XOPEN_SOURCE
 #endif
-])
+])dnl
+
+  AC_REQUIRE([AC_CHECK_INCLUDES_DEFAULT])dnl
+  _AC_CHECK_HEADER_ONCE([wchar.h])
+  _AC_CHECK_HEADER_ONCE([minix/config.h])
+
+dnl Defining __EXTENSIONS__ may break the system headers on some systems.
+dnl (FIXME: Which ones?)
   AC_CACHE_CHECK([whether it is safe to define __EXTENSIONS__],
     [ac_cv_safe_to_define___extensions__],
     [AC_COMPILE_IFELSE(
@@ -464,25 +470,31 @@ dnl prefixes.
           ]AC_INCLUDES_DEFAULT])],
        [ac_cv_safe_to_define___extensions__=yes],
        [ac_cv_safe_to_define___extensions__=no])])
+
+dnl HP-UX 11.11 defines mbstate_t only if _XOPEN_SOURCE is defined to
+dnl 500, regardless of whether compiling with -Ae or -D_HPUX_SOURCE=1.
+dnl But defining _XOPEN_SOURCE may turn *off* extensions on platforms
+dnl not covered by turn-on-extensions macros (notably Dragonfly, Free,
+dnl and OpenBSD, which don't have any equivalent of _NETBSD_SOURCE) so
+dnl it should only be defined when necessary.
   AC_CACHE_CHECK([whether _XOPEN_SOURCE should be defined],
     [ac_cv_should_define__xopen_source],
     [ac_cv_should_define__xopen_source=no
-     AC_COMPILE_IFELSE(
-       [AC_LANG_PROGRAM([[
+    AS_IF([test $ac_cv_header_wchar_h = yes],
+      [AC_COMPILE_IFELSE(
+        [AC_LANG_PROGRAM([[
           #include <wchar.h>
           mbstate_t x;]])],
-       [],
-       [AC_COMPILE_IFELSE(
+        [],
+        [AC_COMPILE_IFELSE(
           [AC_LANG_PROGRAM([[
-             #define _XOPEN_SOURCE 500
-             #include <wchar.h>
-             mbstate_t x;]])],
-          [ac_cv_should_define__xopen_source=yes])])])
+            #define _XOPEN_SOURCE 500
+            #include <wchar.h>
+            mbstate_t x;]])],
+          [ac_cv_should_define__xopen_source=yes])])])])
 
   AC_DEFINE([_ALL_SOURCE])
   AC_DEFINE([_DARWIN_C_SOURCE])
-  test $ac_cv_safe_to_define___extensions__ = yes &&
-    AC_DEFINE([__EXTENSIONS__])
   AC_DEFINE([_GNU_SOURCE])
   AC_DEFINE([_NETBSD_SOURCE])
   AC_DEFINE([_OPENBSD_SOURCE])
@@ -495,8 +507,16 @@ dnl prefixes.
   AC_DEFINE([__STDC_WANT_LIB_EXT2__])
   AC_DEFINE([__STDC_WANT_MATH_SPEC_FUNCS__])
   AC_DEFINE([_TANDEM_SOURCE])
-  test $ac_cv_should_define__xopen_source = yes &&
-    AC_DEFINE([_XOPEN_SOURCE], [500])
+  AS_IF([test $ac_cv_header_minix_config_h = yes],
+    [MINIX=yes
+    AC_DEFINE([_MINIX])
+    AC_DEFINE([_POSIX_SOURCE])
+    AC_DEFINE([_POSIX_1_SOURCE], [2])],
+    [MINIX=])
+  AS_IF([test $ac_cv_safe_to_define___extensions__ = yes],
+    [AC_DEFINE([__EXTENSIONS__])])
+  AS_IF([test $ac_cv_should_define__xopen_source = yes],
+    [AC_DEFINE([_XOPEN_SOURCE], [500])])
 ])# AC_USE_SYSTEM_EXTENSIONS