doc updates for section "Particular Functions"

From 316e468f0b6d251ab07ffc00c075dc7a7bad7b0f Mon Sep 17 00:00:00 2001
From: Bruno Haible <[email protected]>
Date: Fri, 31 Jul 2020 13:15:50 +0200
Subject: [PATCH 1/3] doc: Refer to Gnulib instead of asking clients to provide
 replacement code.

* doc/autoconf.texi (Particular Functions): Point to Gnulib for all macros that
may call AC_LIBOBJ, namely AC_FUNC_ALLOCA, AC_FUNC_MALLOC, AC_FUNC_OBSTACK,
AC_FUNC_REALLOC, AC_FUNC_STRNLEN.
---
 doc/autoconf.texi | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index d4d4331..5d44937 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -4966,6 +4966,10 @@ void *alloca (size_t);
 #endif
 @end group
 @end example
+
+If you don't want to maintain this piece of code in your package manually,
+you can instead use the Gnulib module @code{alloca-opt} or @code{alloca}.
+@xref{Gnulib}.
 @end defmac
 
 @defmac AC_FUNC_CHOWN
@@ -5301,6 +5305,9 @@ rpl_malloc (size_t n)
 
 The result of this macro is cached in the
 @code{ac_cv_func_malloc_0_nonnull} variable.
+
+If you don't want to maintain a @code{malloc.c} file in your package
+manually, you can instead use the Gnulib module @code{malloc-gnu}.
 @end defmac
 
 @defmac AC_FUNC_MBRTOWC
@@ -5379,6 +5386,9 @@ If the obstacks are found, define @code{HAVE_OBSTACK}, else require an
 
 The result of this macro is cached in the @code{ac_cv_func_obstack}
 variable.
+
+The @code{AC_FUNC_OBSTACK} macro is obsolescent.  New programs should use
+Gnulib's @code{obstack} module.  @xref{Gnulib}.
 @end defmac
 
 @defmac AC_FUNC_REALLOC
@@ -5398,6 +5408,9 @@ the native @code{realloc} is not used in the main project.  See
 
 The result of this macro is cached in the
 @code{ac_cv_func_realloc_0_nonnull} variable.
+
+If you don't want to maintain a @code{realloc.c} file in your package
+manually, you can instead use the Gnulib module @code{realloc-gnu}.
 @end defmac
 
 @defmac AC_FUNC_SELECT_ARGTYPES
@@ -5558,6 +5571,9 @@ from AIX 4.3), require an @code{AC_LIBOBJ} replacement for it.
 
 This macro caches its result in the @code{ac_cv_func_strnlen_working}
 variable.
+
+The @code{AC_FUNC_STRNLEN} macro is obsolescent.  New programs should
+use Gnulib's @code{strnlen} module.  @xref{Gnulib}.
 @end defmac
 
 @anchor{AC_FUNC_UTIME_NULL}
-- 
2.7.4

From b601509555f42f95f0f8e40fa9b5a4bed8d9d88a Mon Sep 17 00:00:00 2001
From: Bruno Haible <[email protected]>
Date: Fri, 31 Jul 2020 13:24:36 +0200
Subject: [PATCH 2/3] doc: Refer to Gnulib where it makes sense.

* doc/autoconf.texi (Particular Functions): Point to Gnulib wherever Gnulib has
more workarounds than mentioned for the particular macro, namely for
AC_FUNC_CHOWN, AC_FUNC_FSEEKO, AC_FUNC_GETGROUPS, AC_FUNC_GETMNTENT,
AC_FUNC_MBRTOWC, AC_FUNC_STRERROR_R, AC_FUNC_STRTOLD.
---
 doc/autoconf.texi | 31 +++++++++++++++++++++++++++++--
 1 file changed, 29 insertions(+), 2 deletions(-)

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 5d44937..79ecc9d 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -4982,6 +4982,10 @@ If the @code{chown} function is available and works (in particular, it
 should accept @option{-1} for @code{uid} and @code{gid}), define
 @code{HAVE_CHOWN}.  The result of this macro is cached in the
 @code{ac_cv_func_chown_works} variable.
+
+If you actually want a workaround, that is, a @code{chown} function is
+available and works, you can use the Gnulib module @code{chown}.
+@xref{Gnulib}.
 @end defmac
 
 @anchor{AC_FUNC_CLOSEDIR_VOID}
@@ -5116,6 +5120,10 @@ visible on some systems (e.g., glibc 2.2).  Otherwise linkage problems
 may occur when compiling with @code{AC_SYS_LARGEFILE} on
 largefile-sensitive systems where @code{off_t} does not default to a
 64bit entity.  All systems with @code{fseeko} also supply @code{ftello}.
+
+Gnulib contains a module @code{fseeko}, that invokes @code{AC_FUNC_FSEEKO}
+and also contains workarounds for other portability problems of
+@code{fseeko}.  @xref{Gnulib}.
 @end defmac
 
 @defmac AC_FUNC_GETGROUPS
@@ -5126,9 +5134,13 @@ largefile-sensitive systems where @code{off_t} does not default to a
 @prindex @code{getgroups}
 @caindex func_getgroups_works
 If the @code{getgroups} function is available and works (unlike on
-Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define
-@code{HAVE_GETGROUPS}.  Set @code{GETGROUPS_LIBS} to any libraries
+Ultrix 4.3 and NeXTstep 3.2, where @samp{getgroups (0, 0)} always fails),
+define @code{HAVE_GETGROUPS}.  Set @code{GETGROUPS_LIBS} to any libraries
 needed to get that function.  This macro runs @code{AC_TYPE_GETGROUPS}.
+
+This macro is obsolescent. New programs need not use this macro.  But
+they may want to use the Gnulib module @code{getgroups}, that provides
+workarounds to other portability problems of this function.
 @end defmac
 
 @anchor{AC_FUNC_GETLOADAVG}
@@ -5207,6 +5219,9 @@ IRIX 4, PTX, and UnixWare, respectively.  Then, if
 
 The result of this macro can be overridden by setting the cache variable
 @code{ac_cv_search_getmntent}.
+
+The @code{AC_FUNC_GETMNTENT} macro is obsolescent.  New programs should
+use Gnulib's @code{mountlist} module.  @xref{Gnulib}.
 @end defmac
 
 @defmac AC_FUNC_GETPGRP
@@ -5321,6 +5336,10 @@ type @code{mbstate_t} are properly declared.
 
 The result of this macro is cached in the @code{ac_cv_func_mbrtowc}
 variable.
+
+Gnulib contains a module @code{mbrtowc} that not only ensures that the
+function is declared, but also works around a number of other portability
+problems of this function.
 @end defmac
 
 @defmac AC_FUNC_MEMCMP
@@ -5515,6 +5534,10 @@ the buffer argument.
 
 The result of this macro is cached in the
 @code{ac_cv_func_strerror_r_char_p} variable.
+
+Gnulib contains a module @code{strerror_r} that not only ensures that the
+function has the return type specified by Posix, but also works around a
+dozen of other portability problems of this function.
 @end defmac
 
 @anchor{AC_FUNC_STRFTIME}
@@ -5558,6 +5581,10 @@ If the @code{strtold} function exists and conforms to C99 or later, define
 @code{HAVE_STRTOLD}.
 
 This macro caches its result in the @code{ac_cv_func_strtold} variable.
+
+Gnulib contains a module @code{strtold} that not only ensures that the
+function exists, but also works around a dozen of other portability
+problems of this function.
 @end defmac
 
 @defmac AC_FUNC_STRNLEN
-- 
2.7.4

From 22d59bcb273fe4c2bf6771be9faa1cd184305ff0 Mon Sep 17 00:00:00 2001
From: Bruno Haible <[email protected]>
Date: Fri, 31 Jul 2020 13:26:04 +0200
Subject: [PATCH 3/3] doc: Update some more macro descriptions.

* doc/autoconf.texi (Particular Functions): Mark AC_FUNC_MMAP as obsolescent.
Clarify AC_FUNC_STRCOLL.
---
 doc/autoconf.texi | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 79ecc9d..ffa14c7 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -5393,6 +5393,9 @@ memory.
 
 The result of this macro is cached in the
 @code{ac_cv_func_mmap_fixed_mapped} variable.
+
+This macro is obsolescent, because fixed mappings have become an unreliable
+feature, due to address space layout randomization (ASLR).
 @end defmac
 
 @defmac AC_FUNC_OBSTACK
@@ -5509,7 +5512,8 @@ New programs need not use these macros.
 If the @code{strcoll} function exists and works correctly, define
 @code{HAVE_STRCOLL}.  This does a bit more than
 @samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect
-definitions of @code{strcoll} that should not be used.
+definitions of @code{strcoll} that should not be used.  But it does
+not check against a known bug of this function on Solaris 10.
 
 The result of this macro is cached in the @code{ac_cv_func_strcoll_works}
 variable.
-- 
2.7.4