10.2.4 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 (see 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++. (see 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 (see 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.