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

5.5.2 Particular Function Checks
--------------------------------

These macros check for particular C functions--whether they exist, and
in some cases how they respond when given certain arguments.

 -- Macro: AC_FUNC_ALLOCA
     Check for the ‘alloca’ function.  Define ‘HAVE_ALLOCA_H’ if
     ‘alloca.h’ defines a working ‘alloca’.  If not, look for a builtin
     alternative.  If either method succeeds, define ‘HAVE_ALLOCA’.
     Otherwise, set the output variable ‘ALLOCA’ to
     ‘${LIBOBJDIR}alloca.o’ and define ‘C_ALLOCA’ (so programs can
     periodically call ‘alloca (0)’ to garbage collect).  This variable
     is separate from ‘LIBOBJS’ so multiple programs can share the value
     of ‘ALLOCA’ without needing to create an actual library, in case
     only some of them use the code in ‘LIBOBJS’.  The ‘${LIBOBJDIR}’
     prefix serves the same purpose as in ‘LIBOBJS’ (*note AC_LIBOBJ vs
     LIBOBJS::).

     Source files that use ‘alloca’ should start with a piece of code
     like the following, to declare it properly.

          #include 
          #include 
          #ifdef HAVE_ALLOCA_H
          # include 
          #elif !defined alloca
          # ifdef __GNUC__
          #  define alloca __builtin_alloca
          # elif defined _MSC_VER
          #  include 
          #  define alloca _alloca
          # elif !defined HAVE_ALLOCA
          #  ifdef  __cplusplus
          extern "C"
          #  endif
          void *alloca (size_t);
          # endif
          #endif

     If you don't want to maintain this piece of code in your package
     manually, you can instead use the Gnulib module ‘alloca-opt’ or
     ‘alloca’.  *Note Gnulib::.

 -- Macro: AC_FUNC_CHOWN
     If the ‘chown’ function is available and works (in particular, it
     should accept ‘-1’ for ‘uid’ and ‘gid’), define ‘HAVE_CHOWN’.  The
     result of this macro is cached in the ‘ac_cv_func_chown_works’
     variable.

     If you want a workaround, that is, a ‘chown’ function that is
     available and works, you can use the Gnulib module ‘chown’.  *Note
     Gnulib::.

 -- Macro: AC_FUNC_CLOSEDIR_VOID
     If the ‘closedir’ function does not return a meaningful value,
     define ‘CLOSEDIR_VOID’.  Otherwise, callers ought to check its
     return value for an error indicator.

     Currently this test is implemented by running a test program.  When
     cross compiling the pessimistic assumption that ‘closedir’ does not
     return a meaningful value is made.

     The result of this macro is cached in the
     ‘ac_cv_func_closedir_void’ variable.

     This macro is obsolescent, as ‘closedir’ returns a meaningful value
     on current systems.  New programs need not use this macro.

 -- Macro: AC_FUNC_ERROR_AT_LINE
     If the ‘error_at_line’ function is not found, require an
     ‘AC_LIBOBJ’ replacement of ‘error’.

     The result of this macro is cached in the ‘ac_cv_lib_error_at_line’
     variable.

     The ‘AC_FUNC_ERROR_AT_LINE’ macro is obsolescent.  New programs
     should use Gnulib's ‘error’ module.  *Note Gnulib::.

 -- Macro: AC_FUNC_FNMATCH
     If the ‘fnmatch’ function conforms to Posix, define ‘HAVE_FNMATCH’.

     Unlike the other specific ‘AC_FUNC’ macros, ‘AC_FUNC_FNMATCH’ does
     not replace a broken/missing ‘fnmatch’.  This is for historical
     reasons.  See ‘AC_REPLACE_FNMATCH’ below.

     The result of this macro is cached in the
     ‘ac_cv_func_fnmatch_works’ variable.

     This macro is obsolescent.  New programs should use Gnulib's
     ‘fnmatch-posix’ module.  *Note Gnulib::.

 -- Macro: AC_FUNC_FNMATCH_GNU
     Behave like ‘AC_REPLACE_FNMATCH’ (_replace_) but also test whether
     ‘fnmatch’ supports GNU extensions.  Detect common implementation
     bugs, for example, the bugs in the GNU C Library 2.1.

     The result of this macro is cached in the ‘ac_cv_func_fnmatch_gnu’
     variable.

     This macro is obsolescent.  New programs should use Gnulib's
     ‘fnmatch-gnu’ module.  *Note Gnulib::.

 -- Macro: AC_FUNC_FORK
     This macro checks for the ‘fork’ and ‘vfork’ functions.  If a
     working ‘fork’ is found, define ‘HAVE_WORKING_FORK’.  This macro
     checks whether ‘fork’ is just a stub by trying to run it.

     If ‘vfork.h’ is found, define ‘HAVE_VFORK_H’.  If a working ‘vfork’
     is found, define ‘HAVE_WORKING_VFORK’.  Otherwise, define ‘vfork’
     to be ‘fork’ for backward compatibility with previous versions of
     ‘autoconf’.  This macro checks for several known errors in
     implementations of ‘vfork’ and considers the system to not have a
     working ‘vfork’ if it detects any of them.

     Since this macro defines ‘vfork’ only for backward compatibility
     with previous versions of ‘autoconf’ you're encouraged to define it
     yourself in new code:
          #ifndef HAVE_WORKING_VFORK
          # define vfork fork
          #endif

     The results of this macro are cached in the ‘ac_cv_func_fork_works’
     and ‘ac_cv_func_vfork_works’ variables.  In order to override the
     test, you also need to set the ‘ac_cv_func_fork’ and
     ‘ac_cv_func_vfork’ variables.

 -- Macro: AC_FUNC_FSEEKO
     If the ‘fseeko’ and ‘ftello’ functions are available, define
     ‘HAVE_FSEEKO’.  Define ‘_LARGEFILE_SOURCE’ if necessary to make the
     prototype visible.

     Configure scripts that use ‘AC_FUNC_FSEEKO’ should normally also
     use ‘AC_SYS_LARGEFILE’ to ensure that ‘off_t’ can represent all
     supported file sizes.  *Note AC_SYS_LARGEFILE::.

     The Gnulib module ‘fseeko’ invokes ‘AC_FUNC_FSEEKO’ and also
     contains workarounds for other portability problems of ‘fseeko’.
     *Note Gnulib::.

 -- Macro: AC_FUNC_GETGROUPS
     Perform all the checks performed by ‘AC_TYPE_GETGROUPS’ (*note
     AC_TYPE_GETGROUPS::).  Then, if the ‘getgroups’ function is
     available and known to work correctly, define ‘HAVE_GETGROUPS’.
     Set the output variable ‘GETGROUPS_LIB’ to any libraries needed to
     get that function.

     This macro relies on a list of systems with known, serious bugs in
     ‘getgroups’.  If this list mis-identifies your system's ‘getgroups’
     as buggy, or as not buggy, you can override it by setting the cache
     variable ‘ac_cv_func_getgroups_works’ in a ‘config.site’ file
     (*note Site Defaults::).  Please also report the error to the
     Autoconf Bugs mailing list .

     The Gnulib module ‘getgroups’ provides workarounds for additional,
     less severe portability problems with this function.

 -- Macro: AC_FUNC_GETLOADAVG
     Check how to get the system load averages.  To perform its tests
     properly, this macro needs the file ‘getloadavg.c’; therefore, be
     sure to set the ‘AC_LIBOBJ’ replacement directory properly (see
     *note Generic Functions::, ‘AC_CONFIG_LIBOBJ_DIR’).

     If the system has the ‘getloadavg’ function, define
     ‘HAVE_GETLOADAVG’, and set ‘GETLOADAVG_LIBS’ to any libraries
     necessary to get that function.  Also add ‘GETLOADAVG_LIBS’ to
     ‘LIBS’.  Otherwise, require an ‘AC_LIBOBJ’ replacement for
     ‘getloadavg’ and possibly define several other C preprocessor
     macros and output variables:

       1. Define ‘C_GETLOADAVG’.

       2. Define ‘SVR4’, ‘DGUX’, ‘UMAX’, or ‘UMAX4_3’ if on those
          systems.

       3. If ‘nlist.h’ is found, define ‘HAVE_NLIST_H’.

       4. If ‘struct nlist’ has an ‘n_un.n_name’ member, define
          ‘HAVE_STRUCT_NLIST_N_UN_N_NAME’.  The obsolete symbol
          ‘NLIST_NAME_UNION’ is still defined, but do not depend upon
          it.

       5. Programs may need to be installed set-group-ID (or
          set-user-ID) for ‘getloadavg’ to work.  In this case, define
          ‘GETLOADAVG_PRIVILEGED’, set the output variable ‘NEED_SETGID’
          to ‘true’ (and otherwise to ‘false’), and set ‘KMEM_GROUP’ to
          the name of the group that should own the installed program.

     The ‘AC_FUNC_GETLOADAVG’ macro is obsolescent.  New programs should
     use Gnulib's ‘getloadavg’ module.  *Note Gnulib::.

 -- Macro: AC_FUNC_GETMNTENT
     Check for ‘getmntent’ in the standard C library, and then in the
     ‘sun’, ‘seq’, and ‘gen’ libraries, for UNICOS, IRIX 4, PTX, and
     UnixWare, respectively.  Then, if ‘getmntent’ is available, define
     ‘HAVE_GETMNTENT’ and set ‘ac_cv_func_getmntent’ to ‘yes’.
     Otherwise set ‘ac_cv_func_getmntent’ to ‘no’.

     The result of this macro can be overridden by setting the cache
     variable ‘ac_cv_search_getmntent’.

     The ‘AC_FUNC_GETMNTENT’ macro is obsolescent.  New programs should
     use Gnulib's ‘mountlist’ module.  *Note Gnulib::.

 -- Macro: AC_FUNC_GETPGRP
     Define ‘GETPGRP_VOID’ if it is an error to pass 0 to ‘getpgrp’;
     this is the Posix behavior.  On older BSD systems, you must pass 0
     to ‘getpgrp’, as it takes an argument and behaves like Posix's
     ‘getpgid’.

          #ifdef GETPGRP_VOID
            pid = getpgrp ();
          #else
            pid = getpgrp (0);
          #endif

     This macro does not check whether ‘getpgrp’ exists at all; if you
     need to work in that situation, first call ‘AC_CHECK_FUNC’ for
     ‘getpgrp’.

     The result of this macro is cached in the ‘ac_cv_func_getpgrp_void’
     variable.

     This macro is obsolescent, as current systems have a ‘getpgrp’
     whose signature conforms to Posix.  New programs need not use this
     macro.

 -- Macro: AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
     If ‘link’ is a symbolic link, then ‘lstat’ should treat ‘link/’ the
     same as ‘link/.’.  However, many older ‘lstat’ implementations
     incorrectly ignore trailing slashes.

     It is safe to assume that if ‘lstat’ incorrectly ignores trailing
     slashes, then other symbolic-link-aware functions like ‘unlink’
     also incorrectly ignore trailing slashes.

     If ‘lstat’ behaves properly, define
     ‘LSTAT_FOLLOWS_SLASHED_SYMLINK’, otherwise require an ‘AC_LIBOBJ’
     replacement of ‘lstat’.

     The result of this macro is cached in the
     ‘ac_cv_func_lstat_dereferences_slashed_symlink’ variable.

     The ‘AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK’ macro is obsolescent.
     New programs should use Gnulib's ‘lstat’ module.  *Note Gnulib::.

 -- Macro: AC_FUNC_MALLOC
     If the ‘malloc’ function is compatible with the GNU C library
     ‘malloc’ (i.e., ‘malloc (0)’ returns a valid pointer), define
     ‘HAVE_MALLOC’ to 1.  Otherwise define ‘HAVE_MALLOC’ to 0, ask for
     an ‘AC_LIBOBJ’ replacement for ‘malloc’, and define ‘malloc’ to
     ‘rpl_malloc’ so that the native ‘malloc’ is not used in the main
     project.

     Typically, the replacement file ‘malloc.c’ should look like (note
     the ‘#undef malloc’):

     #include 
     #undef malloc
     
     #include 
     
     /* Allocate an N-byte block of memory from the heap.
        If N is zero, allocate a 1-byte block.  */
     
     void *
     rpl_malloc (size_t n)
     {
       if (n == 0)
         n = 1;
       return malloc (n);
     }

     The result of this macro is cached in the
     ‘ac_cv_func_malloc_0_nonnull’ variable.

     If you don't want to maintain a ‘malloc.c’ file in your package
     manually, you can instead use the Gnulib module ‘malloc-gnu’.

 -- Macro: AC_FUNC_MBRTOWC
     Define ‘HAVE_MBRTOWC’ to 1 if the function ‘mbrtowc’ and the type
     ‘mbstate_t’ are properly declared.

     The result of this macro is cached in the ‘ac_cv_func_mbrtowc’
     variable.

     The Gnulib module ‘mbrtowc’ not only ensures that the function is
     declared, but also works around other portability problems of this
     function.

 -- Macro: AC_FUNC_MEMCMP
     If the ‘memcmp’ function is not available or does not work, require
     an ‘AC_LIBOBJ’ replacement for ‘memcmp’.

     The result of this macro is cached in the
     ‘ac_cv_func_memcmp_working’ variable.

     This macro is obsolescent, as current systems have a working
     ‘memcmp’.  New programs need not use this macro.

 -- Macro: AC_FUNC_MKTIME
     If the ‘mktime’ function is not available, or does not work
     correctly, require an ‘AC_LIBOBJ’ replacement for ‘mktime’.  For
     the purposes of this test, ‘mktime’ should conform to the Posix
     standard and should be the inverse of ‘localtime’.

     The result of this macro is cached in the
     ‘ac_cv_func_working_mktime’ variable.

     The ‘AC_FUNC_MKTIME’ macro is obsolescent.  New programs should use
     Gnulib's ‘mktime’ module.  *Note Gnulib::.

 -- Macro: AC_FUNC_MMAP
     If the ‘mmap’ function exists and works correctly, define
     ‘HAVE_MMAP’.  This checks only private fixed mapping of
     already-mapped memory.

     The result of this macro is cached in the
     ‘ac_cv_func_mmap_fixed_mapped’ variable.

     Note: This macro asks for more than what an average program needs
     from ‘mmap’.  In particular, the use of ‘MAP_FIXED’ fails on HP-UX
     11, whereas ‘mmap’ otherwise works fine on this platform.

 -- Macro: AC_FUNC_OBSTACK
     If the obstacks are found, define ‘HAVE_OBSTACK’, else require an
     ‘AC_LIBOBJ’ replacement for ‘obstack’.

     The result of this macro is cached in the ‘ac_cv_func_obstack’
     variable.

     The ‘AC_FUNC_OBSTACK’ macro is obsolescent.  New programs should
     use Gnulib's ‘obstack’ module.  *Note Gnulib::.

 -- Macro: AC_FUNC_REALLOC
     If the ‘realloc’ function is compatible with the GNU C library
     ‘realloc’ (i.e., ‘realloc (NULL, 0)’ returns a valid pointer),
     define ‘HAVE_REALLOC’ to 1.  Otherwise define ‘HAVE_REALLOC’ to 0,
     ask for an ‘AC_LIBOBJ’ replacement for ‘realloc’, and define
     ‘realloc’ to ‘rpl_realloc’ so that the native ‘realloc’ is not used
     in the main project.  See ‘AC_FUNC_MALLOC’ for details.

     The result of this macro is cached in the
     ‘ac_cv_func_realloc_0_nonnull’ variable.

     If you don't want to maintain a ‘realloc.c’ file in your package
     manually, you can instead use the Gnulib module ‘realloc-gnu’.

 -- Macro: AC_FUNC_SELECT_ARGTYPES
     Determines the correct type to be passed for each of the ‘select’
     function's arguments, and defines those types in
     ‘SELECT_TYPE_ARG1’, ‘SELECT_TYPE_ARG234’, and ‘SELECT_TYPE_ARG5’
     respectively.  ‘SELECT_TYPE_ARG1’ defaults to ‘int’,
     ‘SELECT_TYPE_ARG234’ defaults to ‘int *’, and ‘SELECT_TYPE_ARG5’
     defaults to ‘struct timeval *’.

     This macro is obsolescent, as current systems have a ‘select’ whose
     signature conforms to Posix.  New programs need not use this macro.

 -- Macro: AC_FUNC_SETPGRP
     If ‘setpgrp’ takes no argument (the Posix version), define
     ‘SETPGRP_VOID’.  Otherwise, it is the BSD version, which takes two
     process IDs as arguments.  This macro does not check whether
     ‘setpgrp’ exists at all; if you need to work in that situation,
     first call ‘AC_CHECK_FUNC’ for ‘setpgrp’.  This macro also does not
     check for the Solaris variant of ‘setpgrp’, which returns a ‘pid_t’
     instead of an ‘int’; portable code should only use the return value
     by comparing it against ‘-1’ to check for errors.

     The result of this macro is cached in the ‘ac_cv_func_setpgrp_void’
     variable.

     This macro is obsolescent, as all forms of ‘setpgrp’ are also
     obsolescent.  New programs should use the Posix function ‘setpgid’,
     which takes two process IDs as arguments (like the BSD ‘setpgrp’).

 -- Macro: AC_FUNC_STAT
 -- Macro: AC_FUNC_LSTAT
     Determine whether ‘stat’ or ‘lstat’ have the bug that it succeeds
     when given the zero-length file name as argument.

     If it does, then define ‘HAVE_STAT_EMPTY_STRING_BUG’ (or
     ‘HAVE_LSTAT_EMPTY_STRING_BUG’) and ask for an ‘AC_LIBOBJ’
     replacement of it.

     The results of these macros are cached in the
     ‘ac_cv_func_stat_empty_string_bug’ and the
     ‘ac_cv_func_lstat_empty_string_bug’ variables, respectively.

     These macros are obsolescent, as no current systems have the bug.
     New programs need not use these macros.

 -- Macro: AC_FUNC_STRCOLL
     If the ‘strcoll’ function exists and works correctly, define
     ‘HAVE_STRCOLL’.  This does a bit more than
     ‘AC_CHECK_FUNCS(strcoll)’, because some systems have incorrect
     definitions of ‘strcoll’ that should not be used.  But it does not
     check against a known bug of this function on Solaris 10.

     The result of this macro is cached in the
     ‘ac_cv_func_strcoll_works’ variable.

 -- Macro: AC_FUNC_STRERROR_R
     If ‘strerror_r’ is available, define ‘HAVE_STRERROR_R’, and if it
     is declared, define ‘HAVE_DECL_STRERROR_R’.  If it returns a ‘char
     *’ message, define ‘STRERROR_R_CHAR_P’; otherwise it returns an
     ‘int’ error number.  The Thread-Safe Functions option of Posix
     requires ‘strerror_r’ to return ‘int’, but many systems (including,
     for example, version 2.2.4 of the GNU C Library) return a ‘char *’
     value that is not necessarily equal to the buffer argument.

     The result of this macro is cached in the
     ‘ac_cv_func_strerror_r_char_p’ variable.

     The Gnulib module ‘strerror_r’ not only ensures that the function
     has the return type specified by Posix, but also works around other
     portability problems of this function.

 -- Macro: AC_FUNC_STRFTIME
     Check for ‘strftime’ in the ‘intl’ library, for SCO Unix.  Then, if
     ‘strftime’ is available, define ‘HAVE_STRFTIME’.

     This macro is obsolescent, as no current systems require the ‘intl’
     library for ‘strftime’.  New programs need not use this macro.

 -- Macro: AC_FUNC_STRTOD
     If the ‘strtod’ function does not exist or doesn't work correctly,
     ask for an ‘AC_LIBOBJ’ replacement of ‘strtod’.  In this case,
     because ‘strtod.c’ is likely to need ‘pow’, set the output variable
     ‘POW_LIB’ to the extra library needed.

     This macro caches its result in the ‘ac_cv_func_strtod’ variable
     and depends upon the result in the ‘ac_cv_func_pow’ variable.

     The ‘AC_FUNC_STRTOD’ macro is obsolescent.  New programs should use
     Gnulib's ‘strtod’ module.  *Note Gnulib::.

 -- Macro: AC_FUNC_STRTOLD
     If the ‘strtold’ function exists and conforms to C99 or later,
     define ‘HAVE_STRTOLD’.

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

     The Gnulib module ‘strtold’ not only ensures that the function
     exists, but also works around other portability problems of this
     function.

 -- Macro: AC_FUNC_STRNLEN
     If the ‘strnlen’ function is not available, or is buggy (like the
     one from AIX 4.3), require an ‘AC_LIBOBJ’ replacement for it.

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

     The ‘AC_FUNC_STRNLEN’ macro is obsolescent.  New programs should
     use Gnulib's ‘strnlen’ module.  *Note Gnulib::.

 -- Macro: AC_FUNC_UTIME_NULL
     If ‘utime (FILE, NULL)’ sets FILE's timestamp to the present,
     define ‘HAVE_UTIME_NULL’.

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

     This macro is obsolescent, as all current systems have a ‘utime’
     that behaves this way.  New programs need not use this macro.

 -- Macro: AC_FUNC_VPRINTF
     If ‘vprintf’ is found, define ‘HAVE_VPRINTF’.  Otherwise, if
     ‘_doprnt’ is found, define ‘HAVE_DOPRNT’.  (If ‘vprintf’ is
     available, you may assume that ‘vfprintf’ and ‘vsprintf’ are also
     available.)

     This macro is obsolescent, as all current systems have ‘vprintf’.
     New programs need not use this macro.

 -- Macro: AC_REPLACE_FNMATCH
     If the ‘fnmatch’ function does not conform to Posix (see
     ‘AC_FUNC_FNMATCH’), ask for its ‘AC_LIBOBJ’ replacement.

     The files ‘fnmatch.c’, ‘fnmatch_loop.c’, and ‘fnmatch_.h’ in the
     ‘AC_LIBOBJ’ replacement directory are assumed to contain a copy of
     the source code of GNU ‘fnmatch’.  If necessary, this source code
     is compiled as an ‘AC_LIBOBJ’ replacement, and the ‘fnmatch_.h’
     file is linked to ‘fnmatch.h’ so that it can be included in place
     of the system ‘’.

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

     This macro is obsolescent, as it assumes the use of particular
     source files.  New programs should use Gnulib's ‘fnmatch-posix’
     module, which provides this macro along with the source files.
     *Note Gnulib::.