GNU gettext utilities: AM_ICONV

13.5.6 AM_ICONV in iconv.m4

The AM_ICONV macro tests for the presence of the POSIX/XSI iconv function family in either the C library or a separate libiconv library. If found, it sets the am_cv_func_iconv variable to ‘yes’; it defines HAVE_ICONV to 1 in the autoconf generated configuration file (usually called config.h); it defines ICONV_CONST to ‘const’ or to empty, depending on whether the second argument of iconv() is of type ‘const char **’ or ‘char **’; it sets the variables LIBICONV and LTLIBICONV to the linker options for use in a Makefile (LIBICONV for use without libtool, LTLIBICONV for use with libtool); it adds an ‘-I’ option to CPPFLAGS if necessary. If not found, it sets LIBICONV and LTLIBICONV to empty and doesn’t change CPPFLAGS.

The complexities that AM_ICONV deals with are the following:

Some operating systems have iconv in the C library, for example glibc. Some have it in a separate library libiconv, for example OSF/1 or FreeBSD. Regardless of the operating system, GNU libiconv might have been installed. In that case, it should be used instead of the operating system’s native iconv.
GNU libiconv, if installed, is not necessarily already in the search path (CPPFLAGS for the include file search path, LDFLAGS for the library search path).
GNU libiconv is binary incompatible with some operating system’s native iconv, for example on FreeBSD. Use of an iconv.h and libiconv.so that don’t fit together would produce program crashes.
GNU libiconv, if installed, is not necessarily already in the run time library search path. To avoid the need for setting an environment variable like LD_LIBRARY_PATH, the macro adds the appropriate run time search path options to the LIBICONV variable. This works on most systems, but not on some operating systems with limited shared library support, like SCO.

iconv.m4 is distributed with the GNU gettext package because gettext.m4 relies on it.