File: autoconf.info,  Node: Generic Functions,  Prev: Particular Functions,  Up: Library Functions

5.5.3 Generic Function Checks
-----------------------------

These macros are used to find functions not covered by the "particular"
test macros.  If the functions might be in libraries other than the
default C library, first call ‘AC_CHECK_LIB’ for those libraries.  If
you need to check the behavior of a function as well as find out whether
it is present, you have to write your own test for it (*note Writing
Tests::).

 -- Macro: AC_CHECK_FUNC (FUNCTION, [ACTION-IF-FOUND],
          [ACTION-IF-NOT-FOUND])
     If C function FUNCTION is available, run shell commands
     ACTION-IF-FOUND, otherwise ACTION-IF-NOT-FOUND.  If you just want
     to define a symbol if the function is available, consider using
     ‘AC_CHECK_FUNCS’ instead.  This macro checks for functions with C
     linkage even when ‘AC_LANG(C++)’ has been called, since C is more
     standardized than C++.  (*note Language Choice::, for more
     information about selecting the language for checks.)

     This macro caches its result in the ‘ac_cv_func_FUNCTION’ variable.

 -- Macro: AC_CHECK_FUNCS (FUNCTION..., [ACTION-IF-FOUND],
          [ACTION-IF-NOT-FOUND])
     For each FUNCTION enumerated in the blank-or-newline-separated
     argument list, define ‘HAVE_FUNCTION’ (in all capitals) if it is
     available.  If ACTION-IF-FOUND is given, it is additional shell
     code to execute when one of the functions is found.  You can give
     it a value of ‘break’ to break out of the loop on the first match.
     If ACTION-IF-NOT-FOUND is given, it is executed when one of the
     functions is not found.

     Results are cached for each FUNCTION as in ‘AC_CHECK_FUNC’.

 -- Macro: AC_CHECK_FUNCS_ONCE (FUNCTION...)
     For each FUNCTION enumerated in the blank-or-newline-separated
     argument list, define ‘HAVE_FUNCTION’ (in all capitals) if it is
     available.  This is a once-only variant of ‘AC_CHECK_FUNCS’.  It
     generates the checking code at most once, so that ‘configure’ is
     smaller and faster; but the checks cannot be conditionalized and
     are always done once, early during the ‘configure’ run.


   Autoconf follows a philosophy that was formed over the years by those
who have struggled for portability: isolate the portability issues in
specific files, and then program as if you were in a Posix environment.
Some functions may be missing or unfixable, and your package must be
ready to replace them.

   Suitable replacements for many such problem functions are available
from Gnulib (*note Gnulib::).

 -- Macro: AC_LIBOBJ (FUNCTION)
     Specify that ‘FUNCTION.c’ must be included in the executables to
     replace a missing or broken implementation of FUNCTION.

     Technically, it adds ‘FUNCTION.$ac_objext’ to the output variable
     ‘LIBOBJS’ if it is not already in, and calls ‘AC_LIBSOURCE’ for
     ‘FUNCTION.c’.  You should not directly change ‘LIBOBJS’, since this
     is not traceable.

 -- Macro: AC_LIBSOURCE (FILE)
     Specify that FILE might be needed to compile the project.  If you
     need to know what files might be needed by a ‘configure.ac’, you
     should trace ‘AC_LIBSOURCE’.  FILE must be a literal.

     This macro is called automatically from ‘AC_LIBOBJ’, but you must
     call it explicitly if you pass a shell variable to ‘AC_LIBOBJ’.  In
     that case, since shell variables cannot be traced statically, you
     must pass to ‘AC_LIBSOURCE’ any possible files that the shell
     variable might cause ‘AC_LIBOBJ’ to need.  For example, if you want
     to pass a variable ‘$foo_or_bar’ to ‘AC_LIBOBJ’ that holds either
     ‘"foo"’ or ‘"bar"’, you should do:

          AC_LIBSOURCE([foo.c])
          AC_LIBSOURCE([bar.c])
          AC_LIBOBJ([$foo_or_bar])

     There is usually a way to avoid this, however, and you are
     encouraged to simply call ‘AC_LIBOBJ’ with literal arguments.

     Note that this macro replaces the obsolete ‘AC_LIBOBJ_DECL’, with
     slightly different semantics: the old macro took the function name,
     e.g., ‘foo’, as its argument rather than the file name.

 -- Macro: AC_LIBSOURCES (FILES)
     Like ‘AC_LIBSOURCE’, but accepts one or more FILES in a
     comma-separated M4 list.  Thus, the above example might be
     rewritten:

          AC_LIBSOURCES([foo.c, bar.c])
          AC_LIBOBJ([$foo_or_bar])

 -- Macro: AC_CONFIG_LIBOBJ_DIR (DIRECTORY)
     Specify that ‘AC_LIBOBJ’ replacement files are to be found in
     DIRECTORY, a name relative to the top level of the source tree.
     The replacement directory defaults to ‘.’, the top level directory,
     and the most typical value is ‘lib’, corresponding to
     ‘AC_CONFIG_LIBOBJ_DIR([lib])’.

     ‘configure’ might need to know the replacement directory for the
     following reasons: (i) some checks use the replacement files, (ii)
     some macros bypass broken system headers by installing links to the
     replacement headers (iii) when used in conjunction with Automake,
     within each makefile, DIRECTORY is used as a relative path from
     ‘$(top_srcdir)’ to each object named in ‘LIBOBJS’ and ‘LTLIBOBJS’,
     etc.


   It is common to merely check for the existence of a function, and ask
for its ‘AC_LIBOBJ’ replacement if missing.  The following macro is a
convenient shorthand.

 -- Macro: AC_REPLACE_FUNCS (FUNCTION...)
     Like ‘AC_CHECK_FUNCS’, but uses ‘AC_LIBOBJ(FUNCTION)’ as
     ACTION-IF-NOT-FOUND.  You can declare your replacement function by
     enclosing the prototype in ‘#ifndef HAVE_FUNCTION’.  If the system
     has the function, it probably declares it in a header file you
     should be including, so you shouldn't redeclare it lest your
     declaration conflict.