autoconf: Generic Headers

1 
1 5.6.3 Generic Header Checks
1 ---------------------------
1 
1 These macros are used to find system header files not covered by the
1 "particular" test macros.  If you need to check the contents of a header
1 as well as find out whether it is present, you have to write your own
1 test for it (⇒Writing Tests).
1 
1  -- Macro: AC_CHECK_HEADER (HEADER-FILE, [ACTION-IF-FOUND],
1           [ACTION-IF-NOT-FOUND], [INCLUDES])
1      If the system header file HEADER-FILE is compilable, execute shell
1      commands ACTION-IF-FOUND, otherwise execute ACTION-IF-NOT-FOUND.
1      If you just want to define a symbol if the header file is
1      available, consider using `AC_CHECK_HEADERS' instead.
1 
1      INCLUDES is decoded to determine the appropriate include
1      directives.  If omitted or empty, `configure' will check for both
1      header existence (with the preprocessor) and usability (with the
1      compiler), using `AC_INCLUDES_DEFAULT' for the compile test.  If
1      there is a discrepancy between the results, a warning is issued to
11      the user, and the compiler results are favored (⇒Present But
      Cannot Be Compiled).  In general, favoring the compiler results
1      means that a header will be treated as not found even though the
1      file exists, because you did not provide enough prerequisites.
1 
1      Providing a non-empty INCLUDES argument allows the code to provide
1      any prerequisites prior to including the header under test; it is
11      common to use the argument `AC_INCLUDES_DEFAULT' (⇒Default
      Includes).  With an explicit fourth argument, no preprocessor
1      test is needed.  As a special case, an INCLUDES of exactly `-'
1      triggers the older preprocessor check, which merely determines
1      existence of the file in the preprocessor search path; this should
1      only be used as a last resort (it is safer to determine the actual
1      prerequisites and perform a compiler check, or else use
1      `AC_PREPROC_IFELSE' to make it obvious that only a preprocessor
1      check is desired).
1 
1      This macro caches its result in the `ac_cv_header_HEADER-FILE'
1      variable, with characters not suitable for a variable name mapped
1      to underscores.
1 
1  -- Macro: AC_CHECK_HEADERS (HEADER-FILE..., [ACTION-IF-FOUND],
1           [ACTION-IF-NOT-FOUND], [INCLUDES])
1      For each given system header file HEADER-FILE in the
1      blank-separated argument list that exists, define
1      `HAVE_HEADER-FILE' (in all capitals).  If ACTION-IF-FOUND is
1      given, it is additional shell code to execute when one of the
1      header files is found.  You can give it a value of `break' to
1      break out of the loop on the first match.  If ACTION-IF-NOT-FOUND
1      is given, it is executed when one of the header files is not found.
1 
1      INCLUDES is interpreted as in `AC_CHECK_HEADER', in order to
1      choose the set of preprocessor directives supplied before the
1      header under test.
1 
1      This macro caches its result in the `ac_cv_header_HEADER-FILE'
1      variable, with characters not suitable for a variable name mapped
1      to underscores.
1 
1    Previous versions of Autoconf merely checked whether the header was
1 accepted by the preprocessor.  This was changed because the old test was
1 inappropriate for typical uses.  Headers are typically used to compile,
1 not merely to preprocess, and the old behavior sometimes accepted
11 headers that clashed at compile-time (⇒Present But Cannot Be
 Compiled).  If you need to check whether a header is preprocessable,
1 you can use `AC_PREPROC_IFELSE' (⇒Running the Preprocessor).
1 
1    Actually requiring a header to compile improves the robustness of the
1 test, but it also requires that you make sure that headers that must be
11 included before the HEADER-FILE be part of the INCLUDES, (⇒Default
 Includes).  If looking for `bar.h', which requires that `foo.h' be
1 included before if it exists, we suggest the following scheme:
1 
1 AC_CHECK_HEADERS([foo.h])
1 AC_CHECK_HEADERS([bar.h], [], [],
1 [#ifdef HAVE_FOO_H
1 # include <foo.h>
1 #endif
1 ])
1 
1    The following variant generates smaller, faster `configure' files if
1 you do not need the full power of `AC_CHECK_HEADERS'.
1 
1  -- Macro: AC_CHECK_HEADERS_ONCE (HEADER-FILE...)
1      For each given system header file HEADER-FILE in the
1      blank-separated argument list that exists, define
1      `HAVE_HEADER-FILE' (in all capitals).  This is a once-only variant
1      of `AC_CHECK_HEADERS'.  It generates the checking code at most
1      once, so that `configure' is smaller and faster; but the checks
1      cannot be conditionalized and are always done once, early during
1      the `configure' run.  Thus, this macro is only safe for checking
1      headers that do not have prerequisites beyond what
1      `AC_INCLUDES_DEFAULT' provides.
1