iconv: document not-fixed bugs, using POSIX terminology

[Noah Misch]

iconv.m4 clears HAVE_ICONV if it detects iconv() bugs.  Docs list those bugs
under "Portability problems fixed by Gnulib:".  If changing HAVE_ICONV were
enough to qualify as a fix, then "This function is missing on some platforms"
would also belong under that heading.  I'm proposing to move those bugs under
"not fixed by Gnulib".  It might have been better to add a third section, like
"Portability problems reported by Gnulib preprocessor macros:".

Two of those iconv() bugs involve what POSIX calls "non-identical conversion".
(GNU libc calls it "non-reversible conversion".)  The gnulib docs and code
comments use terms "failures" and "conversion errors", but these bugs don't
entail the distinct POSIX concept of "error" or failure.  Hence, I propose
standardizing on the term "non-identical conversion".  (AIX places 0x1A
https://en.wikipedia.org/wiki/Substitute_character in the output buffer.
Solaris uses an underscore.)

The following patch has those changes.  It also updates modules/iconv_open to
check HAVE_ICONV where modules/iconv checks it.  (Neither module provides
functions to !HAVE_ICONV configurations.)

Incidentally, the AIX iconv() buffer overrun was gone no later than AIX
7100-03-02-1412.  The non-POSIX-conforming return value remains as of AIX
7100-05-06-2028 and AIX 7200-04-01-1939.  Moreover, IBM documents it:
https://www.ibm.com/support/knowledgecenter/ssw_aix_72/i_bostechref/iconv.html

Thanks,
nm


>From 3b99e619bec2f9b0222da05a2bb58ca3e83a258e Mon Sep 17 00:00:00 2001
From: Noah Misch <nmisch@google.com>
Date: Sat, 19 Dec 2020 16:17:45 -0800
Subject: [PATCH] iconv, iconv_open: document not-fixed bugs, using POSIX
 terminology.

* doc/posix-functions/iconv.texi: Move the AIX and Solaris bugs to "not
fixed", because the module only declines to set HAVE_ICONV.  Use term
"non-identical conversions" for events POSIX names that way.
* doc/posix-functions/iconv_open.texi: Move HP-UX EUC-JP bug to "not
fixed", because the module only declines to set HAVE_ICONV.
* m4/iconv.m4 (AM_ICONV_LINK): Use term "non-identical conversions" for
events POSIX names that way.
* modules/iconv_open (Include): Check HAVE_ICONV, like modules/iconv.
---
 ChangeLog                           | 12 ++++++++++++
 doc/posix-functions/iconv.texi      | 17 +++++++++--------
 doc/posix-functions/iconv_open.texi |  6 +++---
 m4/iconv.m4                         |  8 ++++----
 modules/iconv_open                  |  4 +++-
 5 files changed, 31 insertions(+), 16 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 0d8c2ee..bed3e3b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2020-12-19  Noah Misch  <nmisch@google.com>
+
+       iconv, iconv_open: document not-fixed bugs, using POSIX terminology.
+       * doc/posix-functions/iconv.texi: Move the AIX and Solaris bugs to "not
+       fixed", because the module only declines to set HAVE_ICONV.  Use term
+       "non-identical conversions" for events POSIX names that way.
+       * doc/posix-functions/iconv_open.texi: Move HP-UX EUC-JP bug to "not
+       fixed", because the module only declines to set HAVE_ICONV.
+       * m4/iconv.m4 (AM_ICONV_LINK): Use term "non-identical conversions" for
+       events POSIX names that way.
+       * modules/iconv_open (Include): Check HAVE_ICONV, like modules/iconv.
+
 2020-12-19  Bruno Haible  <bruno@clisp.org>
 
        free-posix: Assume future POSIX compliance only on OpenBSD and Solaris.
diff --git a/doc/posix-functions/iconv.texi b/doc/posix-functions/iconv.texi
index 01e7fd1..895afb3 100644
--- a/doc/posix-functions/iconv.texi
+++ b/doc/posix-functions/iconv.texi
@@ -10,12 +10,6 @@ Portability problems fixed by Gnulib:
 @itemize
 @item
 GNU libiconv is not found if installed in @file{$PREFIX/lib}.
-@item
-Failures are not distinguishable from successful returns on some platforms:
-AIX 5.1, Solaris 10.
-@item
-A buffer overrun can occur on some platforms:
-AIX 6.1..7.1.
 @end itemize
 
 Portability problems not fixed by Gnulib:
@@ -32,9 +26,16 @@ cannot be converted to the output character set, glibc's and 
GNU libiconv's
 @code{iconv} stop the conversion.  Some other implementations put an
 implementation-defined character into the output buffer.
 Gnulib provides higher-level facilities @code{striconv} and @code{striconveh}
-(wrappers around @code{iconv}) that deal with conversion errors in a platform
-independent way.
+(wrappers around @code{iconv}) that deal with non-identical conversions in a
+platform independent way.
 @item
 This function returns a positive return value, instead of zero, when
 converting from ISO-8859-1 to UTF-8 on HP-UX 11.
+@item
+This function returns zero, instead of a positive return value, for
+non-identical conversions on some platforms:
+AIX 5.1, Solaris 10.
+@item
+A buffer overrun can occur on some platforms:
+AIX 6.1..7.1.
 @end itemize
diff --git a/doc/posix-functions/iconv_open.texi 
b/doc/posix-functions/iconv_open.texi
index f46cf98..3af3e3b 100644
--- a/doc/posix-functions/iconv_open.texi
+++ b/doc/posix-functions/iconv_open.texi
@@ -10,9 +10,6 @@ Portability problems fixed by either Gnulib module 
@code{iconv} or @code{iconv_o
 @itemize
 @item
 GNU libiconv is not found if installed in @file{$PREFIX/lib}.
-@item
-No converter from EUC-JP to UTF-8 is provided on some platforms:
-HP-UX 11.
 @end itemize
 
 Portability problems fixed by Gnulib module @code{iconv_open}:
@@ -45,4 +42,7 @@ facility @code{striconveh} (a wrapper around @code{iconv}) 
that deals with
 this problem.
 @item
 The set of supported encodings and conversions is system dependent.
+@item
+No converter from EUC-JP to UTF-8 is provided on some platforms:
+HP-UX 11.
 @end itemize
diff --git a/m4/iconv.m4 b/m4/iconv.m4
index f8a536b..d205a62 100644
--- a/m4/iconv.m4
+++ b/m4/iconv.m4
@@ -92,8 +92,8 @@ AC_DEFUN([AM_ICONV_LINK],
 #endif
              ]],
              [[int result = 0;
-  /* Test against AIX 5.1 bug: Failures are not distinguishable from successful
-     returns.  */
+  /* Test against AIX 5.1 bug: Zero return despite non-identical
+     (non-reversible) conversion of one character.  */
   {
     iconv_t cd_utf8_to_88591 = iconv_open ("ISO8859-1", "UTF-8");
     if (cd_utf8_to_88591 != (iconv_t)(-1))
@@ -112,8 +112,8 @@ AC_DEFUN([AM_ICONV_LINK],
         iconv_close (cd_utf8_to_88591);
       }
   }
-  /* Test against Solaris 10 bug: Failures are not distinguishable from
-     successful returns.  */
+  /* Test against Solaris 10 bug: Zero return despite non-identical
+     (non-reversible) conversion of one character.  */
   {
     iconv_t cd_ascii_to_88591 = iconv_open ("ISO8859-1", "646");
     if (cd_ascii_to_88591 != (iconv_t)(-1))
diff --git a/modules/iconv_open b/modules/iconv_open
index 3486901..dba4592 100644
--- a/modules/iconv_open
+++ b/modules/iconv_open
@@ -58,7 +58,9 @@ MAINTAINERCLEANFILES += iconv_open-aix.h iconv_open-hpux.h 
iconv_open-irix.h ico
 EXTRA_DIST           += iconv_open-aix.h iconv_open-hpux.h iconv_open-irix.h 
iconv_open-osf.h iconv_open-solaris.h iconv_open-zos.h
 
 Include:
-<iconv.h>
+#if HAVE_ICONV
+# include <iconv.h>
+#endif
 
 Link:
 $(LTLIBICONV) when linking with libtool, $(LIBICONV) otherwise
-- 
1.8.3.1